REST API経由でSyntheticsモニターを管理する

所有者(オーナー)または管理者

この機能を利用できるかは、 サブスクリプションレベルによります。

Synthetics REST APIを使用して、以下に示すあらゆるタイプのNew Relic Syntheticsモニターを作成して管理します。ping、シンプルブラウザ、スクリプト化ブラウザ、APIテストモニターREST APIを介して、すべてのSyntheticsデータを入手できます。

Synthetics REST APIを使用するには、アカウントのオーナーまたはアドミニストレーターである必要があります。アカウント設定からAPIアクセスをアクティブにし、アドミンユーザーのAPIキーを生成する必要があります。コマンドラインから標準のAPIコールを実行できます。

入手可能なすべてのNew Relic APIの概要については、API入門を参照してください。

機能

Synthetics API(v3)の最新バージョンには、以下の機能が追加されました。

Synthetics API(v3) 機能
POSTリクエストとPUTリクエストのオプションフィールド SIMPLEBROWSERタイプのモニターのオプションは、UIで使用する場合と同じ要領で指定できます。
PATCHリクエスト PUT内のモニターエンティティ全体を指定する代わりに、変更するモニターのフィールドのみを更新できます。また、適切なタイプのモニターを使用していることを前提に、OPTIONを指定することもできます。
400 Bad Request(不正なリクエスト)エラーの詳細 Synthetics API v3以降では、検証エラーが発生すると、できるだけ多くの情報が表示されます。これで、リクエストの問題点を特定しやすくなります。以前のAPIバージョンでは、最初にエラーが発生した時点で検証が中断されていましたが、このAPIではすべての検証が実行され、検証に失敗したすべてのエラーが表示されます。
ページ付け 大きなAPIレスポンスには、適切なページ番号付けが施されます。

Insightsを使用して、APIを介して実行した過去の変更を分析することもできます。

APIにおけるモニタータイプ

以下に、モニターのタイプとAPIにおける呼称を示します。

モニターのタイプ API名
Ping SIMPLE
シンプルブラウザ BROWSER
スクリプト化ブラウザ SCRIPT_BROWSER
APIテスト SCRIPT_API

APIの使用

Synthetics REST APIコールを実行するには、アドミンユーザーのAPIキーを使用する必要があります。アカウントのREST APIキーは機能しません。

このAPIは、すべてのSyntheticsモニターで使用できます。(また、スクリプト化ブラウザ用の追加のAPIメソッドとAPIテストモニターを使用して、これらのモニターに関連付けられたスクリプトを更新することもできます。)APIを介して、すべてのSyntheticsデータを入手できます。APIの例には、cURLコマンドが表示されます。

Synthetics REST APIでは、アカウントのリクエスト速度が1秒あたり3つのリクエストに制限されます。この閾値を超えて行われたリクエストは、429レスポンスコードを返します。

New Relic Syntheticsアカウント内のすべてのモニターのリストを表示するには、GETリクエストをhttps://synthetics.newrelic.com/synthetics/api/v3/monitorsに送信してください。例えば:

curl -v \
     -H 'X-Api-Key:{Admin_User_Key}' https://synthetics.newrelic.com/synthetics/api/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件です。デフォルトは20件です。

以下のように、cURLコマンドにこれらの値を含めることができます。

curl -v \
     -H 'X-Api-Key:${Admin_User_Key}' https://synthetics.newrelic.com/synthetics/api/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"

単一のSyntheticsモニターを表示するには、GETリクエストをhttps://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}に送信してください。次の例では、{id}を特定のモニターIDに置き換えてください。

curl -v \
     -H 'X-Api-Key:{Admin_User_Key}' https://synthetics.newrelic.com/synthetics/api/v3/monitors/{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を返します。

Syntheticsアカウントに新規のモニターを追加するには、モニターを記述するJSONペイロードと共に、POSTリクエストをhttps://synthetics.newrelic.com/synthetics/api/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, MUTED, 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を介してスクリプト化されたモニター用のスクリプトを追加するには、追加のAPIエンドポイントを呼び出して、作成したばかりのモニター用のスクリプトを送信します。検証済みスクリプトの実行を有効にしたプライベートロケーションを使用している場合は、スクリプト実行が検証済みのスクリプトロケーションをご覧ください。

次の例では、以下に示す特定の値を使用してSynthetic REST APIの属性を置き換えます。

curl -v \
     -X POST -H 'X-Api-Key:{Admin_User_Key}' \
     -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/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 Syntheticsの既存モニターを更新するには、PUTリクエストをhttps://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}に送信してください。さらに、スクリプト化モニターの場合、BASE64でエンコードされたスクリプトを更新するの手順に従います。

すべてのフィールドは必須です。ただし、モニターのTYPEは変更できません

次の例では、{id}を特定のモニターIDに置き換え、Synthetic REST APIの属性を独自の値に置き換えてください。

curl -v \
     -X PUT -H 'X-Api-Key:{Admin_User_Key}' \
     -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/v3/monitors/{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 Syntheticsの既存モニターをパッチするには、PATCHリクエストをhttps://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}に送信してください。

次の例では、{id}を特定のモニターIDに置き換え、Synthetic REST APIの属性を独自の値に置き換えてください。

curl -v \
     -X PATCH -H 'X-Api-Key:{Admin_User_Key}' \
     -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/v3/monitors/{id} \
     -d '{ "name" : "updated monitor name" }'

PATCHリクエストの目的は、エンティティ全体を更新する代わりに、New Relic Syntheticsモニターの個別の属性を更新することにあります。これにより、更新する属性のみを提供できます。

リクエストに成功すると、空白の本文と共に、204 No Contentレスポンスが返されます。可能なエラーコード:

  • 400 Bad Request:1つ以上のモニター値が無効であるか、リクエストの形式が無効です。例えば、頻度が範囲外であるか、指定されたロケーションの1つ以上が無効です。(レスポンスの本文に含まれるエラーメッセージを参照してください。)
  • 404 Not Found: 指定されたモニターが存在しません。

New Relic Syntheticsの既存モニターを削除するには、DELETEリクエストを https://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}に送信してください。次の例では、{id}を特定のモニターIDに置き換えてください:

curl -v \
     -H 'X-Api-Key:{Admin_User_Key}' \
     -X DELETE https://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}

リクエストに成功すると、空白の本文と共に、204 No Contentレスポンスが返されます。リクエストに失敗すると、404 Not Foundレスポンスが返されます:指定されたモニターが存在しません。

New Relic Syntheticsで有効なロケーションのリストを取得するには、以下のコマンドを使用します。

curl -v \
     -X GET -H 'X-Api-Key:{Admin_User_Key}' https://synthetics.newrelic.com/synthetics/api/v1/locations

スクリプト化ブラウザとAPIテストモニター用のスクリプトAPI

汎用APIに加えて、スクリプト化ブラウザ(SCRIPT_BROWSER)とAPIテストブラウザ(SCRIPT_API)用のAPIメソッドがいくつかあります。以下に、cURLコマンドの例を示します。

モニターのスクリプトを取得する

お使いのアカウント用のNew Relic Syntheticsで特定のSCRIPT_BROWSERまたはSCRIPT_APIモニターに関連するスクリプトを表示するには、GETリクエストをhttps://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}/scriptに送信してください。{id}を特定のモニターIDに置き換えてください。例えば:

curl -v
     -H 'X-Api-Key: {Admin_User_Key}' 
     https://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}/script

リクエストに成功すると、200 OKのレスポンスが返されます。返されるデータは、次の形式を使用したJSONオブジェクトです。

{
  "scriptText": BASE64 encoded string
}

可能なエラーコード:

  • 403 Forbidden: 指定されたモニターのタイプは、SCRIPT_BROWSERまたはSCRIPT_APIではありません。
  • 404 Not Found: 指定されたモニターが存在しないか、またはモニターに関連付けられたスクリプトが存在しません。
スクリプト化モニターを追加する

REST APIを備えたNew Relic Syntheticsに、新しいスクリプト化されたモニターを追加するには:

  1. 新規モニターを追加するための標準API手順にしたがって、typeSCRIPT_BROWSERまたはSCRIPT_APIとして特定します。
  2. ${MONITOR_UUID}/scriptエンドポイントに対して、新規モニターを、スクリプトのBASE64でエンコードされたバージョンで更新します。

詳細については、を参照してください。

検証済みスクリプトの実行を有効にしたプライベートロケーションを使用している場合は、スクリプト実行が検証済みのスクリプトロケーションをご覧ください。

モニターのスクリプトを更新する

お使いのアカウント用のNew Relic Syntheticsで特定のSCRIPT_BROWSERまたはSCRIPT_APIモニターに関連するスクリプトを更新するには、scriptTextを含むJSONペイロード(必須)と共に、PUTリクエストをhttps://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}/scriptに送信してください。

scriptPayload='{"scriptText":BASE64 encoded string}'


curl -v -X PUT \
     -H 'X-Api-Key:{Admin_User_Key}' \
     -H 'Content-Type: application/json' \
     https://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}/script \
     -d $scriptPayload

検証済みスクリプトの実行を有効にしたプライベートロケーションを使用している場合は、スクリプト実行が検証済みのスクリプトロケーションをご覧ください。

リクエストに成功すると、空白の本文と一緒に204 No Contentのレスポンスが返されます。可能なエラーコード:

  • 400 Bad RequestscriptTextまたは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アルゴリズムをスクリプトとパスワードと一緒に使用します。

{id}を特定のモニターIDに置き換えてください。これは、スクリプトの例です。

var assert = require('assert');
assert.equal('1', '1');

この例では、passwordscriptLocation用のパスワードとして使用します:

curl -v
	-X PUT -H 'X-Api-Key: '{Admin_User_Key}'
	-H 'content-type: application/json'
	https://synthetics.newrelic.com/synthetics/api/v3/monitors/{id}/script
	-d '{ "scriptText": "dmFyIGFzc2VydCA9IHJlcXVpcmUoJ2Fzc2VydCcpOw0KYXNzZXJ0LmVxdWFsKCcxJywgJzEnKTs=","scriptLocations": [ { "name": "my_vse_enabled_location", "hmac": "MjhiNGE4MjVlMDE1N2M4NDQ4MjNjNDFkZDEyYTRjMmUzZDE3NGJlNjU0MWFmOTJlMzNiODExOGU2ZjhkZTY4"} ]}'
     

スクリプト化ブラウザの例

New RelicのREST APIとbashスクリプトを使用して、スクリプト化されたブラウザモニターを作成する例を示します。

スクリプト化ブラウザAPIの例

以下の例に、スクリプト化ブラウザモニターを作成するための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"); 
    }); 
  }); 
});  

Bashスクリプトの例

この例には、SCRIPTED_BROWSERモニターを作成するbashスクリプトが記載されています。

場合によっては、行の折り返しを無効にする-w 0を使用することができます:base64 -w 0 $scriptfile

#!/bin/bash

# Admin API key from your account settings
adminAPIKey=''
# 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 "X-Api-Key:$adminAPIKey" -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 "X-Api-Key:$adminAPIKey" -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

その他のヘルプ

推奨する詳細情報: