API Sintéticos em bulkCreate
. SintéticosBulkCriar A API fornece um endpoint para criar vários monitores sintéticos em uma única operação síncrona.
- Monitoramento pós-incidente - Depois de resolver um incidente, crie monitores para endpoints descobertos para evitar recorrência.
- Integração de serviço - Estabeleça rapidamente o monitoramento de linha de base para novos serviços ou aplicações.
- Fechamento de lacunas - Crie monitores para endpoints críticos não monitorados identificados por meio da descoberta.
- Fluxos de trabalho automatizados - Integre com fluxos de trabalho de descoberta ou gestão de incidentes para automatizar o provisionamento do monitor.
Use esta API para criar até 50 monitores por solicitação. Para criar mais de 50 monitores por solicitação, use SínteticsAssyncBulkCriar API.
Esta API requer Synthetic monitoring(com.snc.uib.sow_synthetics), que está disponível no ServiceNow Store. O usuário solicitante deve ter a função x_snc_sow_synthetics.synthetics_editor. Antes de chamar esta API, pelo menos um MID Server o local deve ser configurado para monitoramento sintético. Para obter instruções, consulte Create synthetic monitoring locations. Além disso, os itens de configuração (ICs) para os endpoints que estão sendo monitorados devem existir no Configuration Management Database (CMDB).
SyntheticsBulkCreate - POST /sn_sow_synthetics/synthetics_bulk_create
Cria vários monitores sintéticos em uma única operação síncrona.
Use este endpoint para fluxos de trabalho orientados por incidentes e operações em lote menores em que a validação e os resultados imediatos são necessários. Este endpoint é compatível com a criação de até 50 monitores por solicitação, com um tamanho máximo de carga de 10 MB.
Este endpoint vincula monitores a incidentes para observabilidade pós-incidente e fornece automaticamente MID Server seleção de local. Os endpoints são avaliados por meio de um processo de seis fases: Correspondência exata de URL, endpoints do mesmo host, endpoints da mesma sub-rede, endpoints da mesma região, qualquer local disponível, e fallback para padrão. Isso garante cobertura de monitoramento ideal sem exigir atribuição manual de localização.
Formato de URL
URL com controle de versão: /api/sn_sow_synthetics//synthetics_bulk_create
URL padrão: /api/sn_sow_synthetics/synthetics_bulk_create
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| api_version | Opcional. Versão do endpoint para acessar. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: Cadeia de caracteres |
| Nome | Descrição |
|---|---|
| Nenhum(a) |
| Nome | Descrição |
|---|---|
| correlation_id | Necessário. Identificador de correlação para rastreamento e telemetria que vincula todos os monitores criados na mesma solicitação. Você pode usar gs.generateGUID() para gerar o id. Tamanho máximo: 200 caracteres Tipo de dados: Cadeia de caracteres |
| endpoints | Necessário. Matriz de objetos de configuração de endpoint para os quais criar monitores. Esta matriz pode conter no máximo 50 objetos por solicitação de API. Tipo de dados: Matriz |
| endpoints.body | Corpo da solicitação para endpoints de POST, PUT ou PATCH. Deve ser uma cadeia de caracteres JSON ou XML válida, dependendo de Tipo de conteúdo cabeçalho. O tamanho máximo é de 10 KB.Tipo de dados: Cadeia de caracteres |
| endpoints.habilitado | Sinalizador que indica se o monitor começará a ser executado imediatamente após a criação. Valores válidos:
Padrão: verdadeiro Tipo de dados: Booliano |
| endpoints.endpoint_id | Necessário. Sys_id do CMDB Item de configuração de endpoint (IC). Tabela: Endpoint HTTP [cmdb_ci_endpoint_http] Tipo de dados: Cadeia de caracteres |
| endpoints.headers | Matriz de cabeçalhos HTTP para o monitor incluir na solicitação de endpoint. Tipo de dados: Matriz Padrão: Matriz vazia (sem cabeçalhos) |
| endpoints.headers.name | Nome do cabeçalho HTTP, como Autorização ou Tipo de conteúdo .Tipo de dados: Cadeia de caracteres |
| endpoints.headers.value | Valor do cabeçalho HTTP, como Token do portador ou aplicação/json .Tipo de dados: Cadeia de caracteres |
| endpoints.interval | Frequência de execução do monitor em minutos. ServiceNow os locais hospedados são limitados a 6 testes por minuto por monitor. Valores válidos: 1-60 Padrão: 5 (executa uma vez a cada cinco minutos) Tipo de dados: Número |
| endpoints.max_latence_ms | Tempo de resposta máximo aceitável em milissegundos. A diretriz geral é de 500 a 5000 ms, dependendo do tipo de endpoint. O monitor verifica esse valor durante o teste e o teste falha se o tempo de resposta exceder esse valor. Padrão: Nulo (sem limite de latência) Tipo de dados: Número |
| endpoints.método | Método HTTP a ser usado. Valores válidos (sem distinção entre maiúsculas e minúsculas):
Padrão: OBTER Tipo de dados: Cadeia de caracteres |
| endpoints.name | Nome de exibição do monitor. Para a criação de monitor orientado por incidentes, um formato de exemplo é [Inc] endpoint_name - service_name .Tamanho máximo: 100 caracteres Padrão: O nome do monitor é gerado automaticamente a partir do nome do endpoint. Tipo de dados: Cadeia de caracteres |
| endpoints.parent_service_sys_id | SYS_id do serviço de negócios compatível com este endpoint. Usado para relatórios de nível de serviço e análise de impacto. Tabela: Serviço de negócios [cmdb_ci_service] Padrão: Nulo Tipo de dados: Cadeia de caracteres |
| endpoints.support_group_sys_id | Sys_id do grupo de suporte responsável por este endpoint. Usado para roteamento e atribuição de alertas. Tabela: Grupo [sys_user_group] Padrão: Nulo Tipo de dados: Cadeia de caracteres |
| endpoints.url | Necessário. URL HTTP ou HTTPS completo para monitorar. Deve começar com http:// ou https:// . Por exemplo, https://api.example.com/health .Tamanho máximo: 2048 caracteres Tipo de dados: Cadeia de caracteres |
| endpoints.valid_http_code | Códigos de status HTTP esperados para uma resposta bem-sucedida, fornecidos como um valor único ou uma lista separada por vírgulas, como "200,201,204" . O monitor verifica esses valores durante o teste e o teste falha se o código de status real não corresponder a um valor na lista. Padrão: 200 Tipo de dados: Cadeia de caracteres |
| idempotency_key | Necessário. Identificador exclusivo (chave) para impedir a criação de monitor duplicado se a mesma solicitação de API for enviada várias vezes. As chaves são mantidas no sistema por 24 horas. Formato: Qualquer cadeia de caracteres de até 200 caracteres, como correlation_idou o padrão Tipo de dados: Cadeia de caracteres |
| incident_id | Sys_id do incidente que acionou a criação do monitor. Usado para acompanhamento e correlação na análise pós-incidente. Se fornecido, os monitores criados serão vinculados a este incidente. Tabela: incidente [incident] Tipo de dados: Cadeia de caracteres |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos da REST API compatíveis .
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Oferece suporte somente a application/json. |
| Autorização | Autenticação básica HTTP ou token do portador OAuth. Formato de autenticação básica: Formato OAuth: |
| Tipo de conteúdo | Formato de dados do corpo da solicitação. Oferece suporte somente a application/json. |
| Cabeçalho | Descrição |
|---|---|
| Tipo de conteúdo | Formato de dados do corpo da resposta. Oferece suporte somente a application/json. |
| Tentar novamente após | Retornado com 503 código de status. Número de segundos a aguardar antes de tentar novamente a solicitação. |
| X-Request-ID | Identificador exclusivo da solicitação de API. Usado para solução de problemas e correlação de log. |
Códigos de status
Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .
| Código de status | Descrição |
|---|---|
| 200 | Bem-sucedido. Todos ou alguns monitores foram criados. Verificar resultsno corpo da resposta para o status de criação de monitor individual. |
| 400 | Solicitação incorreta. Falha na validação da solicitação. Verificar error.codee. error.messageno corpo da resposta para obter detalhes do erro. Causas comuns:
|
| 401 | Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas. |
| 403 | Proibido. O usuário deve ter a função x_snc_sow_synthetics.synthetics_editor para criar monitores. |
| 404 | Não encontrado. O caminho do endpoint da API está incorreto ou o plug-in Monitoramento sintético não está instalado ou ativado. |
| 413 | Carga muito grande. O corpo da solicitação excede o limite de 10 MB. Reduza o número de objetos no endpointsou remover conteúdo de corpo de solicitação grande. |
| 429 | Excesso de solicitações. Limite de taxa excedido, aguarde e tente novamente. Verificar error.details.retry_after_secondsno corpo da resposta pelo número de segundos até que a janela de limite de taxa seja redefinida. O usuário excedeu um dos seguintes:
|
| 500 | Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro. |
| 503 | Serviço indisponível. Monitoramento sintético serviço temporariamente indisponível devido a manutenção ou alta carga. Tente novamente a solicitação após o atraso indicado no Tentar novamente após cabeçalho. |
Parâmetros do corpo da resposta (JSON)
| Nome | Descrição |
|---|---|
| erro | O objeto retornado se a solicitação de API falhar. Tipo de dados: Objeto |
| error.code | Código de erro. Valores possíveis:
Tipo de dados: Cadeia de caracteres |
| error.details | Detalhes adicionais sobre o erro. Os elementos incluídos neste objeto variam com base no tipo de erro. Tipo de dados: Objeto |
| mensagem.erro | Mensagens de erro Tipo de dados: Cadeia de caracteres |
| mensagem | Mensagem sobre o resultado da solicitação de API. Tipo de dados: Cadeia de caracteres |
| resultados | Matriz de objetos que contém o resultado de criação do monitor para cada endpoint. Os resultados do endpoint são listados na mesma ordem fornecida no endpointsmatriz no corpo da solicitação. Tipo de dados: Matriz |
| endpoint_id.endpoint_id | Sys_id do CMDB Item de configuração de endpoint (IC). Tabela: Endpoint HTTP [cmdb_ci_endpoint_http] Tipo de dados: Cadeia de caracteres |
| error_code.error_code | Código de erro se a criação do monitor statusé falha .Valores possíveis:
Tipo de dados: Cadeia de caracteres |
| error_message.error_message | Mensagem de erro se a criação do monitor statusé falha .Tipo de dados: Cadeia de caracteres |
| local.resultados | MID Server local selecionado para o monitor. Tipo de dados: Objeto |
| results.location.name | Nome do MID Server local. Tipo de dados: Cadeia de caracteres |
| results.location.selection_phase | Número da fase usado para selecionar MID Server local. Cada endpoint é avaliado em relação às fases a seguir, começando com a fase Valores possíveis:
Tipo de dados: Número |
| sys_id.location.results.location.sys_id | Sys_id do MID Server local. Tabela: Local sintético [sn_sow_synthetics_location] Tipo de dados: Cadeia de caracteres |
| monitor_name.monitor_name | Nome de exibição do monitor criado. Tipo de dados: Cadeia de caracteres |
| monitor_sys_id.monitor | Sys_id do monitor criado. Tabela: Verificar [sn_sow_synthetics_check] Tipo de dados: Cadeia de caracteres |
| status.results | Monitore o status de criação do endpoint. Valores possíveis:
Tipo de dados: Cadeia de caracteres |
| êxito | Sinalizador que indica se a solicitação de API foi bem-sucedida. Valor possível: Nota:
Este parâmetro só é incluído quando o código de status da resposta é 200 este valor é sempre verdadeiro .Tipo de dados: Booliano |
| resumo | Objeto que resume o resultado da solicitação de API. Tipo de dados: Objeto |
| falha.resumo.falha | Número de monitores que não puderam ser criados. Tipo de dados: Número |
| resumo.bem-sucedido | Número de monitores que foram criados com sucesso. Tipo de dados: Número |
| total_requested | Número total de endpoints incluídos na solicitação de API. Tipo de dados: Número |
Solicitação de curl
Este exemplo cria monitores para três endpoints HTTP descobertos a partir de um incidente resolvido.
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"
}
]
}'Corpo da resposta - Todos os monitores criados com sucesso.
{
"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
}
]
}Corpo da resposta - sucesso parcial.
{
"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
}
]
}Corpo da resposta - erro de limite de taxa.
{
"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
}
}
}