SyntheticsMassenerstellungs-API
Die SyntheticsMassenErstellen Die API stellt einen Endpunkt bereit, um mehrere Synthetic-Überwachungen in einem einzigen synchronen Vorgang zu erstellen.
- Überwachung nach Incidents: Erstellen Sie nach der Lösung eines Incidents Überwachungen für erkannte Endpunkte, um eine Wiederholung zu verhindern.
- Service-Onboarding: Richten Sie schnell die Baseline-Überwachung für neue Services oder Anwendungen ein.
- Lückenabschluss – Erstellen Sie Überwachungen für nicht überwachte kritische Endpunkte, die durch Discovery identifiziert wurden.
- Automatisierte Workflows – Integration in Incident-Management- oder Discovery-Workflows, um die Überwachung der Bereitstellung zu automatisieren.
Verwenden Sie diese API, um bis zu 50 Überwachungen pro Anforderung zu erstellen. Verwenden Sie zum Erstellen von mehr als 50 Überwachungen pro Anforderung SyntheticsAsyncMassenErstellen API.
Diese API erfordert Synthetic monitoring Anwendung (com.snc.uib.SOW_Synthetics), die auf verfügbar ist ServiceNow Store. Der aufrufende Anwender muss über die Rolle x_snc_sow_synthetics.synthetics_editor verfügen. Bevor Sie diese API aufrufen, mindestens eine MID-Server Der Standort muss für die Synthetic-Überwachung konfiguriert werden. Anweisungen dazu finden Sie unter Create synthetic monitoring locations. Darüber hinaus müssen Konfigurationselemente (CIs) für die überwachten Endpunkte in vorhanden sein Configuration Management Database (CMDB).
SyntheticsBulkCreate – POSTEN SIE /sn_SOW_Synthetics/synthetics_Bulk_create
Erstellt mehrere Synthetic-Monitore in einem einzigen synchronen Vorgang.
Verwenden Sie diesen Endpunkt für Incident-gesteuerte Workflows und kleinere Batch-Vorgänge, bei denen eine sofortige Validierung und Ergebnisse erforderlich sind. Dieser Endpunkt unterstützt die Erstellung von bis zu 50 Überwachungen pro Anforderung mit einer maximalen Nutzlastgröße von 10 MB.
Dieser Endpunkt verknüpft die Überwachung von Incidents auf Erkennbarkeit nach Incidents und bietet automatische Funktionen MID-Server Standortauswahl. Endpunkte werden durch einen sechsphasigen Prozess ausgewertet: Genaue URL-Übereinstimmung, Endpunkte des gleichen Hosts, Endpunkte des gleichen Subnetzes, Endpunkte der gleichen Region, beliebiger verfügbarer Standort, und Fallback auf Standard. Dies stellt eine optimale Überwachungsabdeckung sicher, ohne dass eine manuelle Standortzuweisung erforderlich ist.
URL-Format
Versionierte URL: /api/sn_SOW_Synthetics/{api_Version}/synthetics_Bulk_create
Standard-URL: /api/sn_SOW_Synthetics/synthetics_Bulk_create
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| api_version | Optional. Version des Endpunkts, auf den zugegriffen werden soll. Beispiel: v1 Oder v2 . Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| correlation_id | Erforderlich. Korrelationsbezeichner für Nachverfolgung und Telemetrie, der alle in derselben Anforderung erstellten Monitore verknüpft. Sie können verwenden gs.generateGUID() Um die ID zu generieren Maximale Länge: 200 Zeichen Datentyp: Zeichenfolge |
| Endpunkte | Erforderlich. Array von Endpunktkonfigurationsobjekten, für die Überwachungen erstellt werden sollen. Dieses Array kann maximal 50 Objekte pro API-Anforderung enthalten. Datentyp: Array |
| Endpunkte.Textkörper | Anforderungstext für POST-, PUT- oder PATCH-Endpunkte. Muss je nach eine gültige JSON- oder XML-Zeichenfolge sein Inhaltstyp Header. Die maximale Größe beträgt 10 KB.Datentyp: Zeichenfolge |
| Endpunkte.aktiviert | Kennzeichnung, die angibt, ob die Ausführung der Überwachung unmittelbar nach der Erstellung beginnt. Gültige Werte:
Standardwert: wahr Datentyp: Boolesch |
| Endpunkte.Endpunkt_ID | Erforderlich. SYS_ID von CMDB Endpunkt-Konfigurationselement (CI). Tabelle: HTTP-Endpunkt [cmdb_ci_endpoint_http] Datentyp: Zeichenfolge |
| Endpunkte.Header | Array von HTTP-Headern für die Überwachung, die in die Endpunktanforderung aufgenommen werden sollen. Datentyp: Array Standard: Leeres Array (keine Header) |
| endpoints.headers.name | Name des HTTP-Headers, z. B. Autorisierung Oder Inhaltstyp .Datentyp: Zeichenfolge |
| Endpunkte.Header.Wert | Wert des HTTP-Headers, z. B. Bearer-Token Oder Anwendung/JSON .Datentyp: Zeichenfolge |
| endpoints.interval | Häufigkeit der Überwachungsausführung in Minuten. ServiceNow Gehostete Standorte sind auf 6 Tests pro Minute pro Monitor beschränkt. Gültige Werte: 1-60 Standard: 5 (wird alle fünf Minuten ausgeführt) Datentyp: Zahl |
| Endpoints.max_latency_ms | Maximal zulässige Antwortzeit in Millisekunden. Die allgemeine Leitlinie beträgt je nach Endpunkttyp 500 bis 5000 ms. Die Überwachung überprüft beim Testen anhand dieses Werts, und der Test schlägt fehl, wenn die Antwortzeit diesen Wert überschreitet. Standard: Null (kein Latenzschwellenwert) Datentyp: Zahl |
| Endpunkte.method | Zu verwendende HTTP-Methode. Gültige Werte (ohne Berücksichtigung der Groß-/Kleinschreibung):
Standard: GET Datentyp: Zeichenfolge |
| endpoints.name | Anzeigename für den Monitor. Für die Erstellung von Incident-gesteuerten Monitoren ist ein Beispielformat [INC{number}] {endpoint_Name} – {Service_Name} .Maximale Länge: 100 Zeichen Standard: Der Überwachungsname wird automatisch aus dem Endpunktnamen generiert. Datentyp: Zeichenfolge |
| endpoints.parent_service_sys_id | SYS_ID des Business-Service, den dieser Endpunkt unterstützt. Wird für Servicelevel-Berichte und Auswirkungsanalysen verwendet. Tabelle: Business-Service [cmdb_ci_Service] Standard: Null Datentyp: Zeichenfolge |
| endpoints.support_group_sys_id | SYS_ID der Supportgruppe, die für diesen Endpunkt verantwortlich ist. Wird für die Weiterleitung und Zuweisung von Warnungen verwendet. Tabelle: Gruppe [sys_user_group] Standard: Null Datentyp: Zeichenfolge |
| Endpunkte.url | Erforderlich. Vollständige zu überwachende HTTP- oder HTTPS-URL. Muss mit beginnen http:// Oder https:// . Beispiel: https://api.example.com/health .Maximale Länge: 2048 Zeichen Datentyp: Zeichenfolge |
| Endpoints.valid_http_Code | Erwartete HTTP-Statuscodes für eine erfolgreiche Antwort, angegeben als einzelner Wert oder eine durch Kommas getrennte Liste wie „200,201,204“ . Die Überwachung überprüft beim Testen anhand dieser Werte, und der Test schlägt fehl, wenn der tatsächliche Statuscode nicht mit einem Wert in der Liste übereinstimmt. Standard: 200 Datentyp: Zeichenfolge |
| Idepotency_key | Erforderlich. Eindeutiger Bezeichner (Schlüssel), um die Erstellung einer doppelten Überwachung zu verhindern, wenn dieselbe API-Anforderung mehrmals übermittelt wird. Schlüssel werden 24 Stunden im System aufbewahrt. Format: Beliebige Zeichenfolge mit bis zu 200 Zeichen, z. B. correlation_idOder das Muster Datentyp: Zeichenfolge |
| incident_id | SYS_ID des Incidents, der die Monitorerstellung ausgelöst hat. Wird für die Nachverfolgung und Korrelation in der Analyse nach Incident verwendet. Falls angegeben, sind erstellte Überwachungen mit diesem Incident verknüpft. Tabelle: Incident [incident] Datentyp: Zeichenfolge |
Header
Die folgenden Anforderungs- und Antwort-Header gelten nur für diese HTTP-Aktion oder werden auf diese Aktion in einer bestimmten Weise angewendet. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header .
| Header | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Autorisierung | HTTP-Standardauthentifizierung oder OAuth-Bearer-Token. Standardauthentifizierungsformat: OAuth-Format: |
| Inhaltstyp | Datenformat des Anforderungstexts. Unterstützt nur application/json. |
| Header | Beschreibung |
|---|---|
| Inhaltstyp | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Erneut Versuchen Nach | Zurückgegeben mit 503 Statuscode. Anzahl der Sekunden, die gewartet werden soll, bevor die Anforderung erneut versucht wird. |
| X-Anforderung-ID | Eindeutiger Bezeichner für die API-Anforderung. Wird für Fehlerbehebung und Protokollkorrelation verwendet. |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST-API verwendet werden, finden Sie unter REST-API-HTTP-Antwortcodes .
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Alle oder einige Überwachungen wurden erstellt. Überprüfen resultsIm Antworttext für den Erstellungsstatus der einzelnen Überwachung. |
| 400 | Ungültige Anforderung. Anforderungsvalidierung fehlgeschlagen. Überprüfen error.codeUnd error.messageIm Antworttext für Fehlerdetails. Häufige Ursachen:
|
| 401 | Nicht autorisiert Die Anwenderanmeldeinformationen sind falsch oder wurden nicht übergeben. |
| 403 | Unzulässig. Der Anwender muss über die Rolle x_snc_sow_synthetics.synthetics_editor verfügen, um Überwachungen zu erstellen. |
| 404 | Nicht gefunden. Der API-Endpunktpfad ist falsch, oder das Synthetic Monitoring-Plugin ist nicht installiert oder aktiviert. |
| 413 | Nutzlast zu groß. Anforderungstext überschreitet das Limit von 10 MB. Reduzieren Sie die Anzahl der Objekte in endpointsArray, oder entfernen Sie großen Inhalt des Anforderungstexts. |
| 429 | Zu viele Anforderungen. Quotenbegrenzung überschritten, warten Sie, und versuchen Sie es erneut. Überprüfen error.details.retry_after_secondsIm Antworttext für die Anzahl der Sekunden, bis das Quotenbegrenzungsfenster zurückgesetzt wird. Anwender hat einen der folgenden Werte überschritten:
|
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Die Antwort enthält zusätzliche Informationen zum Fehler. |
| 503 | Service nicht verfügbar. Synthetische Überwachung Service aufgrund von Wartung oder hoher Auslastung vorübergehend nicht verfügbar. Wiederholen Sie die Anforderung nach der in angegebenen Verzögerung Erneut Versuchen Nach Header. |
Parameter des Antwort-Haupttexts (JSON)
| Name | Beschreibung |
|---|---|
| Fehler | Objekt, das zurückgegeben wird, wenn die API-Anforderung fehlgeschlagen ist. Datentyp: Objekt |
| Fehler.Code | Fehlercode. Mögliche Werte:
Datentyp: Zeichenfolge |
| error.details | Zusätzliche Details zum Fehler. Die in diesem Objekt enthaltenen Elemente variieren je nach Fehlertyp. Datentyp: Objekt |
| Fehler.Nachricht | Fehlermeldung. Datentyp: Zeichenfolge |
| Nachricht | Nachricht zum Ergebnis der API-Anforderung. Datentyp: Zeichenfolge |
| Ergebnisse | Array von Objekten, die das Überwachungserstellungsergebnis für jeden Endpunkt enthalten. Endpunktergebnisse werden in derselben Reihenfolge aufgeführt, die in angegeben ist endpointsArray im Anforderungstext. Datentyp: Array |
| Results.endpoint_ID | SYS_ID von CMDB Endpunkt-Konfigurationselement (CI). Tabelle: HTTP-Endpunkt [cmdb_ci_endpoint_http] Datentyp: Zeichenfolge |
| Results.error_Code | Fehlercode, wenn die Monitorerstellung erfolgt statusIst Fehlgeschlagen .Mögliche Werte:
Datentyp: Zeichenfolge |
| Ergebnisse.ERROR_message | Fehlermeldung bei der Monitorerstellung statusIst Fehlgeschlagen .Datentyp: Zeichenfolge |
| Ergebnisse.Standort | MID-Server Für den Monitor ausgewählter Standort. Datentyp: Objekt |
| results.location.name | Name von MID-Server Standort. Datentyp: Zeichenfolge |
| results.location.selection_phase | Phasennummer, die zum Auswählen von verwendet wird MID-Server Standort. Jeder Endpunkt wird anhand der folgenden Phasen ausgewertet, beginnend mit Phase Mögliche Werte:
Datentyp: Zahl |
| Ergebnisse.Standort.sys_ID | SYS_ID von MID-Server Standort. Tabelle: Synthetic-Standort [sn_sow_synthetics_location] Datentyp: Zeichenfolge |
| Ergebnisse.Monitor_Name | Anzeigename der erstellten Überwachung. Datentyp: Zeichenfolge |
| Ergebnisse.Monitor_sys_ID | SYS_ID des erstellten Monitors. Tabelle: [sn_sow_synthetics_check] überprüfen Datentyp: Zeichenfolge |
| Ergebnisse.Status | Überwachen Sie den Erstellungsstatus für den Endpunkt. Mögliche Werte:
Datentyp: Zeichenfolge |
| Erfolg | Kennzeichnung, die angibt, ob die API-Anforderung erfolgreich war. Möglicher Wert: Hinweis:
Dieser Parameter ist nur enthalten, wenn der Antwortstatuscode lautet 200 Dieser Wert ist also immer Wahr .Datentyp: Boolesch |
| Zusammenfassung | Objekt, das das Ergebnis der API-Anforderung zusammenfasst. Datentyp: Objekt |
| Zusammenfassung.fehlgeschlagen | Anzahl der Überwachungen, die nicht erstellt werden konnten. Datentyp: Zahl |
| Zusammenfassung.erfolgreich | Anzahl der Monitore, die erfolgreich erstellt wurden. Datentyp: Zahl |
| Summary.total_REQUESTED | Gesamtzahl der in der API-Anforderung enthaltenen Endpunkte. Datentyp: Zahl |
cURL-Anforderung
In diesem Beispiel werden Überwachungen für drei HTTP-Endpunkte erstellt, die aus einem gelösten Incident erkannt wurden.
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"
}
]
}'Antworttext: Alle Monitore wurden erfolgreich erstellt.
{
"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
}
]
}Antworttext: Teilweiser Erfolg.
{
"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
}
]
}Antworttext: Fehler beim Quotenlimit.
{
"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
}
}
}