Synthetics REST APIを使用して、Syntheticsモニターを作成して管理します。
始める前に
重要
2024 年 10 月 22 日に、コンテナ化されたプライベート ミニオン (1 分間あたりの呼出し回数) およびレガシー合成ランタイム バージョンのサポートが終了します。 2024 年 8 月 26 日以降、レガシー合成ランタイム バージョンを使用して新しいモニターを作成することはできなくなります。 外形監視 REST API 、従来の合成ランタイム バージョンを使用したモニターの作成のみをサポートします。 パフォーマンスの低下を避けるために、最新のランタイムを使用して外形監視モニターを管理するには、NerdGraph APIを使用してください。
当社のSynthetics REST APIは、API経由でSyntheticモニターを管理する方法の1つですが、NerdGraph APIを使用することが推奨されています。
権限
外形監視 REST API を使用するには、外形監視関連の権限とが必要です。
NRQLクエリを使用して、APIを介して実行した過去の変更を分析できます。
APIにおけるモニタータイプ
以下に、モニターのタイプとSynthetics REST APIにおける名称を示します。
モニターのタイプ | API名 |
---|---|
Ping |
|
シンプルブラウザ |
|
スクリプト化ブラウザ |
|
APIテスト |
|
APIの使用
合成モニタリングREST APIを使用するには、合成モニターの管理およびユーザーキーの使用が可能である必要があります(REST APIキーは動作しません)。
このAPIは、すべての合成モニターで使用できます。(また、スクリプト化ブラウザ用の追加のAPIメソッドとAPIテストモニターを使用して、これらのモニターに関連付けられたスクリプトを更新することもできます。)このAPIを介して、すべての合成モニタリングデータを入手できます。APIの例には、cURLコマンドが表示されます。
米国ベースのアカウントの場合、次のエンドポイントを使用します:
https://synthetics.newrelic.com/synthetics/api
EUベースのアカウントの場合、次のエンドポイントを使用します:
https://synthetics.eu.newrelic.com/synthetics/api
注意
合成モニタリングREST APIでは、アカウントのリクエスト速度が1秒あたり3つのリクエストに制限されます。この閾値を超えて行われたリクエストは、429
レスポンスコードを返します。
New Relicアカウントに含まれるすべてのモニターのリストを表示するには、GETリクエストを$API_ENDPOINT/v3/monitors
に送信します。例:
curl -v \
-H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors
リクエストが成功すると、 200 OK
レスポンスが返されます。 返されるデータは、次の形式のJSONオブジェクトになります。
{ "monitors": [ { "id": "2a1bc369-7654-489d-918e-f6g135h7i2jk", "name": "monitor1", "type": "BROWSER", "frequency": 60, "uri": "http://example.com", "locations": [ "AWS_US_WEST_1" ], "status": "DISABLED", "slaThreshold": 7, "options": {}, "modifiedAt": "2016-09-26T23:12:46.981+0000", "createdAt": "2016-09-26T23:12:46.981+0000", "userId": 0, "apiVersion": "0.2.2" } ], "count": 1}
クエリの引数:
offset
:モニターカウントのオフセット。デフォルトは0件。たとえば、モニターが40台あり、オフセット値に20を使用すると、21~40のモニターが返されます。limit
:ページあたりに表示される結果は、最高で100件です。デフォルトは50件です。
以下のように、cURLコマンドにこれらの値を含めることができます。
curl -v \
-H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors \
-G -d 'offset=20&limit=100'
ヘッダーには、モニターのページングを容易にするLink
が含まれます。例:
<https://synthetics.newrelic.com/synthetics/api/v3/monitors/?offset=0&limit=20>; rel="first", <https://synthetics.newrelic.com/synthetics/api/v3/monitors/?offset=40&limit=20>; rel="last"
単一の合成モニターを表示するには、GETリクエストを$API_ENDPOINT/v3/monitors/$MONITOR_ID
に送信します。
curl -v \
-H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors/$MONITOR_ID
リクエストが成功すると、 200 OK
レスポンスが返されます。 返されるデータは、次の形式のJSONオブジェクトになります。
{ "id": UUID, "name": string, "type": string, "frequency": integer, "uri": string, "locations": array of strings, "status": string, "slaThreshold": double, "userId": integer, "apiVersion": string}
無効なモニターIDでは404 Not Found: The specified monitor doesn't exist
が返されます。
重要
2024 年 10 月 22 日に、コンテナ化されたプライベート ミニオン (1 分間あたりの呼出し回数) およびレガシー合成ランタイム バージョンのサポートが終了します。 2024 年 8 月 26 日以降、レガシー合成ランタイム バージョンを使用して新しいモニターを作成することはできなくなります。 外形監視 REST API 、従来の合成ランタイム バージョンを使用したモニターの作成のみをサポートします。 パフォーマンスの低下を避けるために、最新のランタイムを使用して外形監視モニターを管理するには、NerdGraph APIを使用してください。
Syntheticsアカウントに新規のモニターを追加するには、モニターを記述するJSONペイロードと共に、POSTリクエストを$API_ENDPOINT/v3/monitors
に送信します。
特に明記しない限り、次の例のすべてのフィールドが必須です。
{"name": string [required],"type": string (SIMPLE, BROWSER, SCRIPT_API, SCRIPT_BROWSER) [required],"frequency": integer (minutes) [required, must be one of 1, 5, 10, 15, 30, 60, 360, 720, or 1440],"uri": string [required for SIMPLE and BROWSER type],"locations": array of strings [at least one required],"status": string (ENABLED, DISABLED) [required],"slaThreshold": double,"options": { "validationString": string [only valid for SIMPLE and BROWSER types], "verifySSL": boolean (true, false) [only valid for SIMPLE and BROWSER types], "bypassHEADRequest": boolean (true, false) [only valid for SIMPLE types], "treatRedirectAsFailure": boolean (true, false) [only valid for SIMPLE types] }}
さらに、REST API 経由でadd the script for a scripted monitorに追加の API エンドポイントを呼び出し、作成したばかりのモニターのスクリプトを送信します。 検証済みのスクリプト実行を有効にしてプライベートロケーションを使用している場合は、 「検証済みのスクリプト実行があるスクリプトの場所」を参照してください。
次の例では、以下に示す特定の値を使用して合成モニタリングREST APIの属性を置き換えます。
curl -v \
-X POST -H "Api-Key:$API_KEY" \
-H 'Content-Type: application/json' $API_ENDPOINT/v3/monitors \
-d '{ "name" : "monitor1", "frequency" : 15, "uri" : "http://my-uri.com", "locations" : [ "AWS_US_WEST_1" ], "type" : "browser", "status" : "enabled", "slaThreshold" : "1.0"}'
リクエストに成功すると、location
ヘッダーで指定された新規作成モニターのURLと共に、201 Created
レスポンスが返されます。可能なエラーコード:
400 Bad Request
:1つ以上のモニター値が無効であるか、リクエストの形式が無効です。例:頻度が範囲外であるか、指定されたロケーションの1つ以上が無効です。(レスポンスの本文に含まれるエラーメッセージを参照してください。)402 Payment Required
:モニターを作成すると、アカウントで購入したチェックの限度額を超える定期的なチェックが増加します。
New Relicで既存のモニターを更新するには、PUTリクエストを$API_ENDPOINT/v3/monitors/$MONITOR_ID
に送信します。さらに、スクリプト化モニターの場合、BASE64でエンコードされたスクリプトを更新するの手順に従います。
全て必須項目です。 ただし、モニターcannotのTYPE
は変更する必要があります。
特定のモニターIDを使用し、合成モニタリングREST APIの属性を特定の値で置き換えます。
curl -v \
-X PUT -H "Api-Key:$API_KEY" \
-H 'Content-Type: application/json' $API_ENDPOINT/v3/monitors/$MONITOR_ID \
-d '{ "name" : "updated monitor name", "type": "monitor type", "frequency" : 15, "uri" : "http://my-uri.com/", "locations" : [ "AWS_US_WEST_1" ], "status" : "enabled", "slaThreshold": "7.0" }'
PUTリクエストの目的は、ターゲットエンティティを置き換えることにあります。既存のモニターを更新する場合、新しいモニターを作成するときにJSONペイロードで使用する、すべての属性が必要になります。
リクエストに成功すると、空白の本文と共に、204 No Content
レスポンスが返されます。可能なエラーコード:
400 Bad Request
:1つ以上のモニター値が無効であるか、リクエストの形式が無効です。たとえば、頻度が範囲外であるか、指定されたロケーションの1つ以上が無効です。(レスポンスの本文に含まれるエラーメッセージを参照してください。)404 Not Found
:指定されたモニターが存在しません。
New Relicで既存のモニターにパッチを適用するには、PATCHリクエストを$API_ENDPOINT/v3/monitors/$MONITOR_ID
に送信します。
特定のモニターIDを使用し、合成モニタリングREST APIの属性を特定の値で置き換えます。
curl -v \
-X PATCH -H "Api-Key:$API_KEY" \
-H 'Content-Type: application/json' $API_ENDPOINT/v3/monitors/$MONITOR_ID \
-d '{ "name" : "updated monitor name" }'
PATCHリクエストの目的は、エンティティ全体を更新する代わりに、合成モニターの個別の属性を更新することにあります。これにより、更新する属性のみを提供できます。
リクエストに成功すると、空白の本文と共に、204 No Content
レスポンスが返されます。可能なエラーコード:
400 Bad Request
:1つ以上のモニター値が無効であるか、リクエストの形式が無効です。たとえば、頻度が範囲外であるか、指定されたロケーションの1つ以上が無効です。(レスポンスの本文に含まれるエラーメッセージを参照してください。)404 Not Found
:指定されたモニターが存在しません。
合成モニタリングで既存のモニターを削除するには、DELETEリクエストを$API_ENDPOINTに送信します/v3/monitors/$MONITOR_ID
curl -v \
-H "Api-Key:$API_KEY" \
-X DELETE $API_ENDPOINT/v3/monitors/$MONITOR_ID
リクエストに成功すると、空白の本文と共に、204 No Content
レスポンスが返されます。リクエストに失敗すると、404 Not Found
レスポンスが返されます:指定されたモニターは存在しません。
合成モニターで有効なロケーションのリストを取得するには、以下のコマンドを使用します。
curl -v \
-X GET -H "Api-Key:$API_KEY" $API_ENDPOINT/v1/locations
スクリプト化ブラウザとAPIテストモニター用のスクリプトAPI
汎用APIに加えて、スクリプト化ブラウザ (SCRIPT_BROWSER
) とAPIテストブラウザ (SCRIPT_API
) 用のAPIメソッドがいくつかあります。以下に、cURLコマンドの例を示します。
お使いのアカウント用の合成モニターで特定のSCRIPT_BROWSER
またはSCRIPT_API
に関連するスクリプトを表示するには、GETリクエストを$API_ENDPOINT/v3/monitors/$MONITOR_ID/script
に送信します。例:
curl -v
-H "Api-Key:$API_KEY"
$API_ENDPOINT/v3/monitors/$MONITOR_ID/script
リクエストが成功すると、 200 OK
レスポンスが返されます。返されるデータは、次の形式のJSONオブジェクトになります。
{ "scriptText": BASE64 encoded string}
可能なエラーコード:
403 Forbidden:
指定されたモニターのタイプは、SCRIPT_BROWSERまたはSCRIPT_APIではありません。404 Not Found:
指定されたモニターが存在しないか、またはモニターに関連付けられたスクリプトが存在しません。
REST APIを備えた合成モニターに、新しいスクリプト化されたモニターを追加する
新規モニターを追加するための標準API手順に従って、
type
をSCRIPT_BROWSER
またはSCRIPT_API
として特定します。$MONITOR_UUID/script
エンドポイントに対するスクリプトのBASE64エンコードバージョンで新規モニターを更新します。詳細については、例を参照してください。
検証済みスクリプトの実行を有効にしたプライベートロケーションを使用している場合は、スクリプト実行が検証済みのスクリプトロケーションをご覧ください。
特定のSCRIPT_BROWSER
またはSCRIPT_API
モニターに関連するスクリプトを更新するには、/v3/monitors/$MONITOR_ID/script
を含むJSONペイロード(必須)と共に、PUTリクエストを$API_ENDPOINTscriptText
に送信します。
scriptPayload='{"scriptText":BASE64 encoded string}'
curl -v -X PUT \
-H "Api-Key:$API_KEY" \
-H 'Content-Type: application/json' \
$API_ENDPOINT/v3/monitors/$MONITOR_UUID/script \
-d $scriptPayload
検証済みスクリプトの実行を有効にしたプライベートロケーションを使用している場合は、スクリプト実行が検証済みのスクリプトロケーションをご覧ください。
リクエストに成功すると、空白の本文と一緒に204 No Content
のレスポンスが返されます。可能なエラーコード:
400 Bad Request:
scriptText
またはhmac
に対する無効のBASE64でエンコードされた文字列です。403 Forbidden:
指定されたモニターのタイプがSCRIPT_BROWSER
またはSCRIPT_API
ではありません。404 Not Found:
指定されたモニターが存在しません。
検証済みのスクリプト実行をオンにしたプライベートロケーション用にモニターを作成または更新するときは、scriptLocations
を使用してパスワードを設定する必要があります:
{ "scriptText": BASE64 encoded String, "scriptLocations": [ { "name": Location name, "hmac" BASE64 encoded String of SHA256 HMAC for location } ]}
HMAC文字列を生成するために使用するパスワードは、プライベートロケーションに設定されたパスワードと一致する必要があります。検証済みスクリプトの実行を有効にしたロケーションが複数存在する場合、各ロケ―ションでHMACを計算する必要があります。HMAC文字列を生成する場合は、SHA256アルゴリズムをスクリプトとパスワードと一緒に使用します。
以下はスクリプトの例です。
var assert = require('assert');assert.equal('1', '1');
この例では、password
をscriptLocation
のパスワードとして使用します。
curl -v
-X PUT -H "Api-Key:$API_KEY"
-H 'content-type: application/json'
$API_ENDPOINT}/v3/monitors/$MONITOR_ID/script
-d '{ "scriptText": "dmFyIGFzc2VydCA9IHJlcXVpcmUoJ2Fzc2VydCcpOw0KYXNzZXJ0LmVxdWFsKCcxJywgJzEnKTs=","scriptLocations": [ { "name": "my_vse_enabled_location", "hmac": "MjhiNGE4MjVlMDE1N2M4NDQ4MjNjNDFkZDEyYTRjMmUzZDE3NGJlNjU0MWFmOTJlMzNiODExOGU2ZjhkZTY4ZQ=="} ]}'
重要
BASE64でエンコーディングする前に、スクリプトと計算されたHMAC値の両方から最後の改行文字を削除する必要があります。
計算ステップ:
- スクリプトから HMAC 値を計算します。 1 つの方法は次を使用することです。
cat script | openssl dgst -sha256 -hmac "password" > hmac
- openssl によって改行文字が追加された場合は、改行文字を削除します。
- HMACを改行なしでBASE64でエンコードします。
スクリプト化ブラウザの例
New RelicのREST APIとbashスクリプトを使用して、スクリプト化されたブラウザモニターを作成する例を示します。
以下の例では、スクリプトによるブラウザモニタを作成するためのcurlコマンドを示しています。
スクリプトの上部で、特定の値で変数を交換します。
scriptfile
変数については、作成するスクリプトのファイル名を特定します。以下に示すのは、この例で使用するためにsample_synth_script.js
として保存できるサンプルスクリプトです:var assert = require("assert");$browser.get("http://example.com").then(function(){// Check the H1 title matches "Example Domain"return $browser.findElement($driver.By.css("h1")).then(function(element){return element.getText().then(function(text){assert.equal("Example Domain", text, "Page H1 title did not match");});});}).then(function(){// Check that the external link matches "http://www.iana.org/domains/example"return $browser.findElement($driver.By.css("div > p > a")).then(function(element){return element.getAttribute("href").then(function(link){assert.equal("http://www.iana.org/domains/example", link, "More information link did not match");});});});
この例では、SCRIPTED_BROWSER
モニターを作成するbashスクリプトが記載されています。
ヒント
場合によっては、行の折り返しを無効にする-w 0
を使用することができます。 base64 -w 0 $scriptfile
#!/bin/bash
# API key from your account settings
API_KEY=''
# Other attributes found at https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/attributes-synthetics-rest-api#api-attributes
monitorName='Test API Script'
monitorType='SCRIPT_BROWSER'
frequency=1440
locations='"AWS_US_WEST_1", "AWS_US_EAST_1"'
slaThreshold=7.0
# Location of the file with your script
scriptfile=sample_synth_script.js
# Test that the script file exists (does not validate content)
if [ -e "$scriptfile" ]
then
script=$(cat "$scriptfile")
payload="{ \"name\" : \"$monitorName\", \"frequency\" : $frequency, \"locations\" : [ $locations ], \"status\" : \"ENABLED\", \"type\" : \"$monitorType\", \"slaThreshold\" : $slaThreshold, \"uri\":\"\"}"
echo "Creating monitor"
# Make curl call to API and parse response headers to get monitor UUID
shopt -s extglob # Required to trim whitespace; see below
while IFS=':' read key value; do
# trim whitespace in "value"
value=${value##+([[:space:]])}; value=${value%%+([[:space:]])}
case "$key" in
location) LOCATION="$value"
;;
HTTP*) read PROTO STATUS MSG <<< "$key{$value:+:$value}"
;;
esac
done < <(curl -sS -i -X POST -H "Api-Key:$API_KEY" -H 'Content-Type:application/json' https://synthetics.newrelic.com/synthetics/api/v3/monitors -d "$payload")
# Validate monitor creation & add script unless it failed
if [ $STATUS = 201 ]; then
echo "Monitor created, $LOCATION "
echo "Uploading script"
# base64 encode script
encoded=`echo "$script" | base64`
scriptPayload="{\"scriptText\":\"$encoded\"}"
curl -s -X PUT -H "Api-Key:$API_KEY" -H 'Content-Type:application/json' "$LOCATION/script" -d $scriptPayload
echo "Script uploaded"
else
echo "Monitor creation failed"
fi
else
echo "script file not found, not creating monitor"
fi