Use a API REST do Sintético para criar e gerenciar o monitor Sintético.
Antes que você comece
Importante
Em 22 de outubro de 2024, encerraremos a vida útil das versões conteinerizadas minion privado (chamadas por minuto) e legado runtime do Synthetics. A partir de 26 de agosto de 2024, não será mais possível criar novos monitores usando o legado runtime das versões sintéticas. A API REST do Sintético suporta apenas a criação monitor usando o tempo de execução substituto das versões do Synthetics. Use API NerdGraph para gerenciar seu monitor Sintético usando nossos tempos de execução mais recentes para evitar degradação.
Nossa API REST Sintético é uma forma de gerenciar seu monitor Sintético via API, mas a forma recomendada é usar nossa API NerdGraph.
Permissões
Para usar a API REST do Sintético, você deve ter permissões relacionadas ao Sintético e um .
Você pode usar a consulta NRQL para analisar alterações anteriores feitas por meio da API.
monitor tipos na API
Estes são os tipos de monitores e como eles são mencionados na API REST Sintético:
Tipo de monitor | Nome da API |
---|---|
Pingar |
|
Browser simples |
|
Browser com script |
|
Teste de API |
|
Usar a API
Para usar a API REST de monitoramento sintético, você deve ter a capacidade de gerenciar o monitor Sintético e usar uma chave de usuário (a chave de API REST não funcionará).
Esta API pode ser usada para todos os monitores Sintético. (Métodos API adicionais para browser com script e monitor de teste de API também estão disponíveis para atualizar o script associado a esses monitores.) Todos os dados de monitoramento sintético estão disponíveis através da API. Exemplos de API mostram o comando curl.
Para contas baseadas nos EUA, use o seguinte endpoint:
https://synthetics.newrelic.com/synthetics/api
Para contas baseadas na UE, use o seguinte endpoint:
https://synthetics.eu.newrelic.com/synthetics/api
Cuidado
A API REST de monitoramento sintético limita a taxa de solicitações de uma conta a três solicitações por segundo. As solicitações feitas além desse limite retornarão um código de resposta 429
.
Para visualizar uma lista de todos os monitores em sua conta New Relic, envie uma solicitação GET para $API_ENDPOINT/v3/monitors
. Por exemplo:
$curl -v \> -H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors
Uma solicitação bem-sucedida retornará uma resposta 200 OK
. Os dados retornados serão um objeto JSON no seguinte formato:
{ "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}
Argumentos de consulta:
offset
: O deslocamento da contagem do monitor. O padrão é 0. Por exemplo, se você tiver 40 monitores e usar um valor de deslocamento de 20, ele retornará o monitor 21-40.limit
: O número de resultados por página, máximo 100. O padrão é 50.
Você pode incluí-los em seu comando curl da seguinte maneira:
$curl -v \> -H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors \> -G -d 'offset=20&limit=100'
Os cabeçalhos incluem um Link
para ajudá-lo a paginar facilmente seu monitor. Por exemplo:
<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"
Para visualizar um único monitor Sintético, envie uma solicitação GET para $API_ENDPOINT/v3/monitors/$MONITOR_ID
.
$curl -v \> -H "Api-Key:$API_KEY" $API_ENDPOINT/v3/monitors/$MONITOR_ID
Uma solicitação bem-sucedida retornará uma resposta 200 OK
. Os dados retornados serão um objeto JSON no seguinte formato:
{ "id": UUID, "name": string, "type": string, "frequency": integer, "uri": string, "locations": array of strings, "status": string, "slaThreshold": double, "userId": integer, "apiVersion": string}
Um ID de monitor inválido retornará 404 Not Found: The specified monitor doesn't exist
.
Importante
Em 22 de outubro de 2024, encerraremos a vida útil das versões conteinerizadas minion privado (chamadas por minuto) e legado runtime do Synthetics. A partir de 26 de agosto de 2024, não será mais possível criar novos monitores usando o legado runtime das versões sintéticas. A API REST do Sintético suporta apenas a criação monitor usando o tempo de execução substituto das versões do Synthetics. Use API NerdGraph para gerenciar seu monitor Sintético usando nossos tempos de execução mais recentes para evitar degradação.
Para adicionar um novo monitor à sua conta Sintético, envie uma solicitação POST para $API_ENDPOINT/v3/monitors
com uma carga JSON que descreve o monitor.
Todos os campos no exemplo a seguir são obrigatórios, salvo indicação em contrário:
{ "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] }}
Além disso, para add the script for a scripted monitor por meio da chamada de API REST, um endpoint adicional de API para enviar o script para o monitor recém-criado. Se você estiver usando localização privada com execução de script verificada habilitada, consulte locais de script com execução de script verificada.
Substitua o atributo da API REST de monitoramento sintético no exemplo a seguir por seus valores específicos:
$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"}'
Uma solicitação bem-sucedida retornará uma resposta 201 Created
, com o URI do monitor recém-criado especificado no cabeçalho location
. Os possíveis códigos de erro incluem:
400 Bad Request
: um ou mais valores de monitor são inválidos ou o formato da solicitação é inválido. Por exemplo: a frequência está fora dos limites ou um ou mais dos locais especificados são inválidos. (Veja a mensagem de erro no corpo da resposta.)402 Payment Required
: a criação do monitor aumentará suas verificações programadas além do limite de verificações compradas da sua conta.
Para atualizar um monitor existente no New Relic, envie uma solicitação PUT para $API_ENDPOINT/v3/monitors/$MONITOR_ID
. Além disso, para monitores com script, siga os procedimentos para atualizar o script codificado em BASE64.
Todos os campos são necessários. Porém, o TYPE
do monitor cannot será alterado.
Use um ID de monitor específico e substitua o atributo da API REST de monitoramento sintético por seus valores específicos.
$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" $}'
As solicitações PUT destinam-se a substituir a entidade alvo, portanto, todos os atributos necessários no payload JSON ao criar um novo monitor também são necessários ao atualizar um monitor existente.
Uma solicitação bem-sucedida retornará uma resposta 204 No Content
, com corpo vazio. Os possíveis códigos de erro incluem:
400 Bad Request
: um ou mais valores de monitor são inválidos ou o formato da solicitação é inválido. Por exemplo, a frequência está fora dos limites ou um ou mais locais especificados são inválidos. (Veja a mensagem de erro no corpo da resposta.)404 Not Found
: o monitor especificado não existe.
Para corrigir um monitor existente no New Relic, envie uma solicitação PATCH para $API_ENDPOINT/v3/monitors/$MONITOR_ID
.
Use um ID de monitor específico e substitua o atributo da API REST de monitoramento sintético por seus valores específicos.
$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" }'
As solicitações PATCH têm como objetivo atualizar o atributo individual do seu monitor Sintético ao invés de atualizar a entidade inteira, portanto você pode fornecer apenas o atributo que deseja atualizar.
Uma solicitação bem-sucedida retornará uma resposta 204 No Content
, com corpo vazio. Os possíveis códigos de erro incluem:
400 Bad Request
: um ou mais valores de monitor são inválidos ou o formato da solicitação é inválido. Por exemplo, a frequência está fora dos limites ou um ou mais dos locais especificados são inválidos. (Veja a mensagem de erro no corpo da resposta.)404 Not Found
: o monitor especificado não existe.
Para excluir um monitor existente no monitoramento sintético, envie uma solicitação DELETE para o endpoint/v3/monitors/$MONITOR_ID
:
$curl -v \> -H "Api-Key:$API_KEY" \> -X DELETE $API_ENDPOINT/v3/monitors/$MONITOR_ID
Uma solicitação bem-sucedida retornará uma resposta 204 No Content
, com corpo vazio. Uma solicitação malsucedida retornará a resposta 404 Not Found
: O monitor especificado não existe.
Para recuperar a lista de locais válidos em seu monitor Sintético, utilize o seguinte comando:
$curl -v \> -X GET -H "Api-Key:$API_KEY" $API_ENDPOINT/v1/locations
API de script para browser com script e monitor de teste de API
Além da API geral, existem vários métodos de API para o browser com script (SCRIPT_BROWSER
) e browser de teste de API (SCRIPT_API
). Esses exemplos mostram o comando curl.
Para visualizar o script associado a um SCRIPT_BROWSER
ou SCRIPT_API
específico nos monitores Sintético da sua conta, envie uma solicitação GET para $API_ENDPOINT/v3/monitors/$MONITOR_ID/script
. Por exemplo:
$curl -v$ -H "Api-Key:$API_KEY"$ $API_ENDPOINT/v3/monitors/$MONITOR_ID/script
Uma solicitação bem-sucedida retornará uma resposta 200 OK
. Os dados retornados serão um objeto JSON no seguinte formato:
{ "scriptText": BASE64 encoded string}
Os possíveis códigos de erro incluem:
403 Forbidden:
O monitor especificado não é do tipo script ou script.404 Not Found:
O monitor especificado não existe ou o script associado ao monitor não existe.
Para adicionar um novo monitor com script aos seus monitores Sintético com a API REST:
Siga os procedimentos padrão da API para adicionar um novo monitor e identifique o
type
comoSCRIPT_BROWSER
ouSCRIPT_API
.Atualize o novo monitor com uma versão do script codificada em BASE64 para o endpoint
$MONITOR_UUID/script
.Para obter mais informações, consulte o exemplo.
Se você estiver usando localização privada com execução de script verificada habilitada, consulte locais de script com execução de script verificada.
Para atualizar o script associado a um monitor SCRIPT_BROWSER
ou SCRIPT_API
específico, envie uma solicitação PUT para $API_ENDPOINT/v3/monitors/$MONITOR_ID/script
com uma carga JSON que contém scriptText
(obrigatório).
$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
Se você estiver usando localização privada com execução de script verificada habilitada, consulte locais de script com execução de script verificada.
Uma solicitação bem-sucedida retornará uma resposta 204 No Content
com corpo vazio. Os possíveis códigos de erro incluem:
400 Bad Request:
Sequência codificada em BASE64 inválida parascriptText
ouhmac
.403 Forbidden:
O monitor especificado não é do tipoSCRIPT_BROWSER
ouSCRIPT_API
.404 Not Found:
O monitor especificado não existe.
Ao criar ou atualizar um monitor para localização privada que tenha a execução de script verificada ativada, você deve usar scriptLocations
para definir a senha:
{ "scriptText": BASE64 encoded String, "scriptLocations": [ { "name": Location name, "hmac" BASE64 encoded String of SHA256 HMAC for location } ]}
A senha utilizada para gerar a string HMAC deve corresponder à senha definida para a localização privada. Se você tiver vários locais com a execução de script verificada ativada, cada local deverá ter o HMAC calculado. Ao gerar a string HMAC, use o algoritmo SHA256 com o script e a senha.
Aqui está um exemplo para o script:
var assert = require('assert');assert.equal('1', '1');
Este exemplo usa password
como senha para 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==" }]}'
Importante
Você deve remover o último caractere de nova linha do script e do valor HMAC calculado antes da codificação em BASE64.
Etapas de cálculo:
- Calcule o valor HMAC do script. Uma maneira é usar:
cat script | openssl dgst -sha256 -hmac "password" > hmac
- Remova o caractere de nova linha se algum tiver sido adicionado pelo openssl.
- Codifique o HMAC em BASE64 sem quebras de linha.
Exemplo de browser com script
Aqui está um exemplo de uso da API REST da New Relic e do script bash para criar um script com monitor de browser.
O exemplo a seguir mostra o comando curl para criar um script com do monitor do browser.
Na parte superior do script, substitua as variáveis pelos seus valores específicos.
Para a variável
scriptfile
, identifique o nome do arquivo do script a ser criado. Aqui está um exemplo de script que pode ser salvo comosample_synth_script.js
para usar no exemplo: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");});});});
Este exemplo mostra o script bash que criará o monitor SCRIPTED_BROWSER
.
Dica
Em alguns casos, você pode querer usar -w 0
, o que desativará a quebra de linha: 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