SyntheticsBulkCreate API
SyntheticsBulkCreate API は、1 回の同期操作で複数の synthetic モニターを作成するためのエンドポイントを提供します。
- インシデントの事後監視:インシデントを解決した後、検出されたエンドポイントのモニターを作成して再発を防ぎます。
- サービスオンボーディング:新しいサービスやアプリケーションのベースライン監視を迅速に確立します。
- ギャップの埋め合わせ:ディスカバリーによって特定された監視対象外の重要なエンドポイントのモニターを作成します。
- 自動ワークフロー:インシデント管理またはディスカバリーワークフローと統合して、監視プロビジョニングを自動化します。
この API を使用して、要求ごとに最大 50 台のモニターを作成します。要求ごとに 50 を超えるモニターを作成するには、 SyntheticsAsyncBulkCreate API を使用します。
この API には、ServiceNow Store で利用可能な Synthetic monitoring アプリケーション (com.snc.uib.sow_synthetics) が必要です。呼び出し元ユーザーには x_snc_sow_synthetics.synthetics_editor ロールが必要です。この API を呼び出す前に、Synthetics モニタリング用に少なくとも 1 つの MID サーバー 場所を設定する必要があります。手順については、「Create synthetic monitoring locations」を参照してください。さらに、監視対象のエンドポイントの構成アイテム (CI) が Configuration Management Database (CMDB)に存在している必要があります。
SyntheticsBulkCreate - POST /sn_sow_synthetics/synthetics_bulk_create
1 回の同期操作で複数の Synthetics モニターを作成します。
このエンドポイントは、即時の検証と結果が必要なインシデント主導型のワークフローや小規模なバッチ操作に使用します。このエンドポイントは、要求ごとに最大 50 台のモニターの作成をサポートし、最大ペイロードサイズは 10 MB です。
このエンドポイントは、インシデント後の観測可能性のために監視をインシデントにリンクし、 MID サーバー 場所を自動的に選択します。エンドポイントは、URL の完全一致、同じホストエンドポイント、同じサブネットエンドポイント、同じリージョンエンドポイント、利用可能な場所、デフォルトへのフォールバックの 6 段階のプロセスを通じて評価されます。これにより、手動で場所をアサインしなくても最適な監視範囲が確保されます。
URL 形式
バージョニングされた URL: /api/sn_sow_synthetics/{api_version}/synthetics_bulk_create
デフォルト URL: /api/sn_sow_synthetics/synthetics_bulk_create
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ：文字列 |
| 名前 | 説明 |
|---|---|
| なし |
| 名前 | 説明 |
|---|---|
| correlation_id | 必須です。同じ要求で作成されたすべてのモニターをリンクする追跡とテレメトリの相関識別子。 gs.generateGUID() を使用して ID を生成できます。 最大長:200 文字 データタイプ：文字列 |
| エンドポイント | 必須です。モニターを作成するエンドポイント構成オブジェクトのアレイ。このアレイには、API 要求ごとに最大 50 個のオブジェクトを含めることができます。 データタイプ：アレイ |
| endpoints.body | POST、PUT、または PATCH エンドポイントの要求本文。Content-Type ヘッダーに応じて、有効な JSON または XML 文字列である必要があります。最大サイズは 10KB です。データタイプ：文字列 |
| endpoints.enabled | モニターの作成直後に実行を開始するかどうかを示すフラグ。 有効な値：
デフォルト：true データタイプ：ブーリアン |
| endpoints.endpoint_id | 必須です。CMDBエンドポイント構成アイテム (CI) のSys_id。 テーブル:HTTP エンドポイント [cmdb_ci_endpoint_http] データタイプ：文字列 |
| endpoints.headers | エンドポイント要求に含めるモニターの HTTP ヘッダーのアレイ。 データタイプ：アレイ デフォルト:空のアレイ (ヘッダーなし) |
| endpoints.headers.name | Authorization や Content-Type などの HTTP ヘッダーの名前。データタイプ：文字列 |
| endpoints.headers.value | ベ アラートークン や アプリケーション/json などの HTTP ヘッダーの値。データタイプ：文字列 |
| endpoints.interval | モニターの実行頻度 (分単位)。 ServiceNow ホストされている場所は、モニターごとに 1 分あたり 6 回のテストに制限されています。 有効な値:1〜60 デフォルト:5 (5 分に 1 回実行) データタイプ：数値 |
| endpoints.max_latency_ms | 許容可能な最大応答時間 (ミリ秒)。一般的なガイドラインは、エンドポイントタイプに応じて 500 〜 5000 ミリ秒です。 モニターはテスト時にこの値と照合し、応答時間がこの値を超えるとテストは失敗します。 デフォルト:null (レイテンシしきい値なし) データタイプ：数値 |
| endpoints.method | 使用する HTTP メソッド。 有効な値 (大文字と小文字の区別なし):
デフォルト：GET データタイプ：文字列 |
| endpoints.name | モニターの表示名。インシデント駆動型のモニター作成の場合、形式の例は [INC{number}] {endpoint_name} - {service_name} です。最大長:100 文字 デフォルト:モニター名はエンドポイント名から自動的に生成されます。 データタイプ：文字列 |
| endpoints.parent_service_sys_id | このエンドポイントがサポートするビジネスサービスのSys_id。サービスレベルレポートと影響分析に使用されます。 テーブル:ビジネスサービス [cmdb_ci_service] デフォルト値:null データタイプ：文字列 |
| endpoints.support_group_sys_id | このエンドポイントを担当するサポートグループのSys_id。アラートのルーティングとアサインに使用されます。 テーブル： Group [sys_user_group] デフォルト値:null データタイプ：文字列 |
| endpoints.url | 必須です。監視する完全な HTTP または HTTPS URL。http:// または https:// で始める必要があります。たとえば、 https://api.example.com/health などです。最大長:2048 文字 データタイプ：文字列 |
| endpoints.valid_http_code | 応答が成功した場合に想定される HTTP ステータスコード。単一の値または 「200,201,204」などのカンマ区切りリストとして指定されます。 モニターはテスト時にこれらの値と照合し、実際のステータスコードがリスト内の値と一致しない場合は不合格になります。 デフォルト:200 データタイプ：文字列 |
| idempotency_key | 必須です。同じ API 要求が複数回送信された場合に重複したモニターが作成されないようにする一意の識別子 (キー)。 キーはシステムに 24 時間保持されます。 形式: correlation_id またはパターン データタイプ：文字列 |
| incident_id | モニターの作成をトリガーしたインシデントのSys_id。インシデントの事後分析での追跡と相関に使用されます。 指定した場合、作成されたモニターはこのインシデントにリンクされます。 テーブル：インシデント [incident] データタイプ：文字列 |
ヘッダー
次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 承認 | 応答本文のデータフォーマット。application/json のみをサポートします。 |
| 認証 | HTTP ベーシック認証または OAuth ベアラートークン。 ベーシック認証形式: OAuth 形式: |
| Content-Type | 要求本文のデータ形式。application/json のみをサポートします。 |
| ヘッダー | 説明 |
|---|---|
| Content-Type | 応答本文のデータフォーマット。application/json のみをサポートします。 |
| 再試行後 | ステータスコード 503 で返されます。要求を再試行するまでの待機秒数。 |
| X-Request-ID | API 要求の一意の識別子。トラブルシューティングとログ相関に使用されます。 |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。すべてまたは一部のモニターが作成されました。応答本文の results で、個々のモニターの作成ステータスを確認します。 |
| 400 | 要求が正しくありません。要求の検証に失敗しました。エラーの詳細については、応答本文の error.code と error.message を確認してください。 一般的な原因:
|
| 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 |
| 403 | 禁止されました。モニターを作成するには、ユーザーに x_snc_sow_synthetics.synthetics_editor ロールが必要です。 |
| 404 | 見つかりません。API エンドポイントパスが正しくないか、Synthetic Monitoring プラグインがインストールされていないか、アクティブ化されていません。 |
| 413 | ペイロードが大きすぎます。要求本文が 10MB の制限を超えています。endpointsアレイ内のオブジェクト数を減らすか、大きな要求本文のコンテンツを削除します。 |
| 429 | 要求が多すぎます。レート制限を超えました。待ってから再試行してください。応答本文の error.details.retry_after_seconds で、レート制限ウィンドウがリセットされるまでの秒数を確認します。 ユーザーが次のいずれかを超えました:
|
| 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 |
| 503 | サービスが利用不可になっています。メンテナンスまたは高負荷のため、 Synthetic モニタリング サービスが一時的に利用できません。Retry-After ヘッダーに示された遅延の後に要求を再試行します。 |
応答本文のパラメーター (JSON)
| 名前 | 説明 |
|---|---|
| エラー | API 要求が失敗した場合に返されるオブジェクト。 データタイプ: オブジェクト |
| error.code | エラーコード。 可能な値：
データタイプ：文字列 |
| error.details | エラーに関するその他の詳細。 このオブジェクトに含まれる要素は、エラーの種類によって異なります。 データタイプ: オブジェクト |
| error.message | エラーメッセージ。 データタイプ：文字列 |
| メッセージ | API 要求の結果に関するメッセージ。 データタイプ：文字列 |
| results | 各エンドポイントのモニター作成結果を含むオブジェクトのアレイ。 エンドポイントの結果は、要求本文の endpoints アレイと同じ順序で一覧表示されます。 データタイプ：アレイ |
| results.endpoint_id | CMDBエンドポイント構成アイテム (CI) のSys_id。 テーブル:HTTP エンドポイント [cmdb_ci_endpoint_http] データタイプ：文字列 |
| results.error_code | モニターの作成 status に 失敗した場合のエラーコード。可能な値：
データタイプ：文字列 |
| results.error_message | モニターの作成 status が 失敗した場合のエラーメッセージ。データタイプ：文字列 |
| results.location | MID サーバー モニター用に選択された場所。 データタイプ: オブジェクト |
| results.location.name | MID サーバー場所の名前。 データタイプ：文字列 |
| results.location.selection_phase | MID サーバー場所の選択に使用されるフェーズ番号。 各エンドポイントは、フェーズ 可能な値：
データタイプ：数値 |
| results.location.sys_id | MID サーバー場所のSys_id。 テーブル:Synthetic 場所 [sn_sow_synthetics_location] データタイプ：文字列 |
| results.monitor_name | 作成したモニターの表示名。 データタイプ：文字列 |
| results.monitor_sys_id | 作成したモニターのSys_id。 テーブル:チェック [sn_sow_synthetics_check] データタイプ：文字列 |
| results.status | エンドポイントの作成ステータスを監視します。 可能な値：
データタイプ：文字列 |
| 成功 | API 要求が成功したかどうかを示すフラグ。 可能な値: 注:
このパラメーターは、応答ステータスコードが 200 の場合にのみ含まれるため、この値は常に true です。データタイプ：ブーリアン |
| サマリー | API 要求の結果を要約するオブジェクト。 データタイプ: オブジェクト |
| summary.failed | 作成できなかったモニターの数。 データタイプ：数値 |
| summary.successful | 正常に作成されたモニターの数。 データタイプ：数値 |
| summary.total_requested | API 要求に含まれるエンドポイントの合計数。 データタイプ：数値 |
cURL 要求
この例では、解決済みインシデントから検出された 3 つの HTTP エンドポイントの監視を作成します。
curl -X POST 'https://instance.service-now.com/api/sn_sow_synthetics/bulk_create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-u 'username:password' \
-d '{
"incident_id": "a1b2c3d4e5f6789012345678",
"idempotency_key": "INC-INC0012345-20260401T120000",
"correlation_id": "550e8400-e29b-41d4-a716-446655440000",
"endpoints": [
{
"endpoint_id": "e1f2g3h4i5j6789012345678",
"name": "[INC0012345] Payment API Health - Payment Gateway",
"url": "https://api.payment.example.com/health",
"method": "GET",
"interval": 2,
"enabled": true,
"parent_service_sys_id": "s1t2u3v4w5x6789012345678",
"support_group_sys_id": "g1h2i3j4k5l6789012345678",
"valid_http_code": "200",
"max_latency_ms": 500
},
{
"endpoint_id": "k1l2m3n4o5p6789012345678",
"name": "[INC0012345] Payment Transaction API - Payment Gateway",
"url": "https://api.payment.example.com/v2/transactions",
"method": "POST",
"interval": 5,
"enabled": true,
"parent_service_sys_id": "s1t2u3v4w5x6789012345678",
"support_group_sys_id": "g1h2i3j4k5l6789012345678",
"valid_http_code": "200,201",
"max_latency_ms": 1000,
"headers": [
{
"name": "Authorization",
"value": "Bearer test-token"
},
{
"name": "Content-Type",
"value": "application/json"
}
],
"body": "{\"amount\": 100, \"currency\": \"USD\"}"
},
{
"endpoint_id": "q1r2s3t4u5v6789012345678",
"name": "[INC0012345] Customer Portal Status - Payment Gateway",
"url": "https://portal.payment.example.com/status",
"method": "GET",
"interval": 10,
"enabled": true,
"parent_service_sys_id": "s1t2u3v4w5x6789012345678",
"valid_http_code": "200"
}
]
}'応答本文:すべてのモニターが正常に作成されました。
{
"success": true,
"message": "Bulk creation completed. 3 monitors created successfully, 0 failed validation.",
"summary": {
"total_requested": 3,
"successful": 3,
"failed": 0
},
"results": [
{
"endpoint_id": "e1f2g3h4i5j6789012345678",
"status": "created",
"monitor_sys_id": "m1n2o3p4q5r6789012345678",
"monitor_name": "[INC0012345] Payment API Health - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
},
{
"endpoint_id": "k1l2m3n4o5p6789012345678",
"status": "created",
"monitor_sys_id": "r1s2t3u4v5w6789012345678",
"monitor_name": "[INC0012345] Payment Transaction API - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
},
{
"endpoint_id": "q1r2s3t4u5v6789012345678",
"status": "created",
"monitor_sys_id": "x1y2z3a4b5c6789012345678",
"monitor_name": "[INC0012345] Customer Portal Status - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
}
]
}応答本文:部分的に成功。
{
"success": true,
"message": "Bulk creation completed. 2 monitors created successfully, 1 failed validation.",
"summary": {
"total_requested": 3,
"successful": 2,
"failed": 1
},
"results": [
{
"endpoint_id": "e1f2g3h4i5j6789012345678",
"status": "created",
"monitor_sys_id": "m1n2o3p4q5r6789012345678",
"monitor_name": "[INC0012345] Payment API Health - Payment Gateway",
"location": {
"sys_id": "l1m2n3o4p5q6789012345678",
"name": "US-East-1 MID Server",
"selection_phase": 2
},
"error_message": null,
"error_code": null
},
{
"endpoint_id": "invalid-endpoint-id",
"status": "failed",
"monitor_sys_id": null,
"monitor_name": null,
"location": null,
"error_message": "Invalid endpoint_id: No endpoint found with sys_id 'invalid-endpoint-id' in cmdb_ci_endpoint_http table.",
"error_code": "INVALID_ENDPOINT_ID"
},
{
"endpoint_id": "q1r2s3t4u5v6789012345678",
"status": "created",
"monitor_sys_id": "x1y2z3a4b5c6789012345678",
"monitor_name": "[INC0012345] Customer Portal Status - Payment Gateway",
"location": {
"sys_id": "w1x2y3z4a5b6789012345678",
"name": "EU-West-1 MID Server",
"selection_phase": 4
},
"error_message": null,
"error_code": null
}
]
}応答本文:レート制限エラー。
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. You have made 11 requests in the last minute. Limit is 10 requests per minute.",
"details": {
"limit": 10,
"window": "per_minute",
"retry_after_seconds": 45
}
}
}