Usando a API do Blob Storage para cadernos

A API Notebooks do New Relic permite criar, ler, atualizar e excluir cadernos programaticamente, incluindo o conteúdo completo do bloco (consultas NRQL, texto). Os cadernos são armazenados como blobs versionados, o que significa que cada salvamento produz uma nova revisão imutável que você pode recuperar mais tarde.

Use esta API para:

Automatize a criação de notebooks a partir de modelos de incidentes, runbooks ou pipeline de CI/CD
Sincronizar o conteúdo do notebook a partir do controle de versão ou de ferramentas de autoria externas
Crie integrações que preencham notebooks de forma programática durante as investigações

Importante

Notebooks usar múltiplas APIs

A superfície da API Notebooks é dividida entre dois sistemas:

Blob Storage API lida com o conteúdo do notebook (blocos, histórico de versões)
NerdGraph lida com operações no nível da entidade (listar, renomear, tags, metadados da organização)
Essa separação é intencional. O Blob Storage API é otimizado para transferência de conteúdo de arquivo e controle de versão; o NerdGraph é otimizado para consultas e mutações de entidade estruturadas.

Pré-requisitos

Uma contaNew Relic com uma chave de API de usuário
Seu ID da organização do New Relic
Devidas permissões para gerenciar notebooks

Autenticação

Todas as requisições de API Notebooks exigem autenticação usando uma chave de API de usuário New Relic.

Gere uma chave de API:

Acesse one.newrelic.com
Clique em seu nome no canto superior direito
Selecione API Keys
Crie uma chave User (não uma chave de Browser ou chave de licença)

Incluir nos cabeçalhos da requisição:

bash

$Api-Key: NRAK-YOUR-USER-API-KEY

Dica

O Blob Storage API também suporta contexto de login, portanto, ao chamar a API de uma interface autenticada como um usuário New Relic, o cabeçalho Api-Key não é necessário.

Endpoint base

https://blob-api.service.newrelic.com/v1/e

Para contas da região da UE, use:

https://blob-api.service.eu.newrelic.com/v1/e

Operações de Conteúdo de Caderno

Cria uma nova entidade de caderno com conteúdo de blob inicial.

Endpoint

POST /v1/e/organizations/{orgId}/Notebooks

Parâmetro de solicitação [#create-params]

Parâmetro	Localização	Tipo de dados	Descrição
`orgId`	Caminho	Corda	Obrigatório. Seu ID da organização New Relic .
`Api-Key`	Cabeçalho	Corda	Obrigatório. Sua chave de API do usuário.
`Content-Type`	Cabeçalho	Corda	Obrigatório. Deve ser `application/json` .
`NewRelic-Entity`	Cabeçalho	string JSON	Obrigatório. Objeto JSON com metadados da entidade do caderno (veja abaixo).
Corpo da requisição	Corpo	JSON	Obrigatório. Conteúdo do notebook no formato JSON (versão + blocos).

`NewRelic-Entity` [#create-entity-header]

Campo	Tipo de dados	Descrição
`name`	Corda	Obrigatório. O nome do caderno. Deve ser único no escopo da organização.

Formato do corpo do caderno [#create-body-format]

Campo	Tipo de dados	Descrição
`version`	Corda	Versão do esquema da carga do caderno. Use `"1"` .
`blocks`	Matriz	Lista ordenada de blocos de notebook ( NRQL , texto, etc.). Uma matriz vazia cria um notebook em branco.

Campo

Tipo de dados

Descrição

version

Corda

Versão do esquema da carga do caderno. Use

"1"

blocks

Matriz

Lista ordenada de blocos de notebook (

NRQL

, texto, etc.). Uma matriz vazia cria um notebook em branco.

Exemplos de conteúdo de interface declarativa [#create-declarative-ui]

Os exemplos a seguir mostram como estruturar o conteúdo do widget do caderno usando o formato de interface declarativa.

Widget Markdown

Use viz.markdown para renderizar texto estático, rótulos ou legendas de limite ao lado de seus gráficos:

{
  "type": "widget",
  "content": {
    "type": "visualization",
    "id": "viz.markdown",
    "props": {
      "text": "# My dashboard\n\n### Cost thresholds (monthly)\n- $0 – $200 → Good\n- $200 – $500 → Warning\n- $500+ → Critical"
    }
  }
}

Widget de Billboard com consulta NRQL

Use viz.billboard para exibir um único valor de métrica com limites opcionais codificados por cores:

{
  "type": "widget",
  "props": {
    "title": "Total usage this month"
  },
  "content": {
    "type": "visualization",
    "id": "viz.billboard",
    "props": {
      "nrqlQueries": [
        {
          "query": "FROM Transaction SELECT count(*) SINCE 1 month ago",
          "accountIds": [1234567]
        }
      ],
      "thresholdsWithSeriesOverrides": {
        "thresholds": [
          { "to": 200, "severity": "success" },
          { "from": 200, "to": 500, "severity": "warning" },
          { "from": 500, "severity": "critical" }
        ]
      },
      "facet": { "showOtherSeries": false },
      "platformOptions": { "ignoreTimeRange": false },
      "chartStyles": { "lineInterpolation": "linear" }
    }
  }
}

Solicitação de amostra [#create-sample-request]

bash

$curl -X POST \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks \
>  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>  -H 'Content-Type: application/json' \
>  -H 'NewRelic-Entity: {"name": "My awesome notebook"}' \
>  -d '{
$    "version": "1",
$    "blocks": []
$  }'

Resposta de amostra [#create-sample-response]

{
  "entityGuid": "<YOUR_ENTITY_GUID>",
  "blobId": "<YOUR_BLOB_ID>",
  "blobVersionEntity": {
    "entityGuid": "<YOUR_ENTITY_GUID>",
    "version": 1
  }
}

Importante

Salve o entityGuid da resposta. Você precisará disso para ler, atualizar e excluir o notebook.

Recupera o conteúdo mais recente de um notebook.

Endpoint

GET /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

Parâmetro de solicitação [#read-params]

Parâmetro

Localização

Tipo de dados

É obrigatório?

Descrição

orgId

Caminho

Corda

Sim

Seu ID da organização

New Relic

entityGuid

Caminho

Corda

Sim

O GUID da entidade do caderno.

Api-Key

Cabeçalho

Corda

Sim

Sua chave de API do usuário.

Solicitação de amostra [#read-sample-request]

bash

$curl -X GET \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

Resposta de amostra [#read-sample-response]

{
  "type": "declarative",
  "version": 1,
  "content": [
    {
      "type": "container",
      "props": {
        "layout": "stack"
      },
      "content": [
        {
          "type": "widget",
          "props": {},
          "content": {
            "type": "visualization",
            "id": "viz.billboard",
            "props": {
              "nrqlQueries": [
                {
                  "query": "FROM PageView SELECT count(*) SINCE 3 days ago",
                  "accountIds": [1]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Cria uma nova versão de um caderno existente substituindo o conteúdo. A versão anterior é retida por até 1 dia (consulte Recuperar versões anteriores).

Endpoint

POST /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

Parâmetro de solicitação [#update-params]

Parâmetro	Localização	Tipo de dados	É obrigatório?	Descrição
`orgId`	Caminho	Corda	Sim	Seu ID da organização New Relic .
`entityGuid`	Caminho	Corda	Sim	O GUID da entidade do caderno.
`Api-Key`	Cabeçalho	Corda	Sim	Sua chave de API do usuário.
`Content-Type`	Cabeçalho	Corda	Sim	Deve ser `application/json` .
Corpo da requisição	Corpo	JSON	Sim	Conteúdo do notebook atualizado.

Solicitação de amostra [#update-sample-request]

bash

$curl -X POST \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>  -H 'Content-Type: application/json' \
>  -d '{
$    "type": "declarative",
$    "version": 1,
$    "content": [
$      {
$        "type": "container",
$        "props": {
$          "layout": "stack"
$        },
$        "content": [
$          {
$            "type": "widget",
$            "props": {
$              "title": ""
$            },
$            "content": {
$              "type": "visualization",
$              "id": "viz.billboard",
$              "props": {
$                "nrqlQueries": [
$                  {
$                    "query": "FROM PageView SELECT count(*) SINCE 2 days ago",
$                    "accountIds": [1]
$                  }
$                ]
$              }
$            }
$          }
$        ]
$      }
$    ]
$  }'

Resposta de amostra [#update-sample-response]

{
  "entityGuid": "<YOUR_ENTITY_GUID>",
  "blobId": "<YOUR_BLOB_ID>",
  "blobVersionEntity": {
    "entityGuid": "<YOUR_ENTITY_GUID>",
    "version": 2
  }
}

Exclui um caderno e seu conteúdo.

Endpoint

DELETE /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

Parâmetro de solicitação [#delete-params]

Parâmetro

Localização

Tipo de dados

É obrigatório?

Descrição

orgId

Caminho

Corda

Sim

Seu ID da organização

New Relic

entityGuid

Caminho

Corda

Sim

O GUID da entidade do notebook a ser excluído.

Api-Key

Cabeçalho

Corda

Sim

Sua chave de API do usuário.

Solicitação de amostra [#delete-sample-request]

bash

$curl -X DELETE \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

Resposta de amostra [#delete-sample-response]

Retorna HTTP 204 No Content em caso de exclusão bem-sucedida.

Notebook as versões são retidas por 1 dia. Para recuperar uma revisão anterior, primeiro liste as versões recentes via NRQL, depois busque o blob específico.

Passo 1 — Listar as últimas 5 versões

Execute esta consulta NRQL no criador de consulta para reunir os IDs de blob e timestamps das últimas 5 alterações:

FROM Entity
SELECT uniques(tuple(updatedAt, content.id))
WHERE id = '<entity guid>'
SINCE 1 day ago
LIMIT 5

Etapa 2 — Recuperar uma versão específica [#retrieve-specific-version]

Use o content.id do resultado de NRQL para buscar o conteúdo dessa versão:

bash

$curl -X GET \
>  https://blob-api.service.newrelic.com/v1/blobs/<content.id> \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

Operações de entidade (NerdGraph)

Operações no nível da entidade, como listagem, renomeação e tag, usam NerdGraph em vez do Blob Storage API.

Listar todos os notebooks

query listAllNotebooks {
  actor {
    entityManagement {
      entitySearch(query: "type='NOTEBOOK'") {
        entities {
          id
          name
        }
      }
    }
  }
}

Dica

A criação da entidade é totalmente transacional, portanto, um notebook fica imediatamente disponível por meio da API. No entanto, se você listar notebooks por meio da consulta actor.entitySearch legada, pode haver um pequeno atraso de propagação entre a criação e o notebook aparecer nos resultados da lista.

Renomear um notebook

mutation changeNotebookName {
  entityManagementUpdateNotebook(
    id: "<entity guid>"
    notebookEntity: { name: "<new name>" }
  ) {
    entity {
      name
    }
  }
}

Atualizar tags do caderno

Importante

As atualizações de tag são uma operação de substituição. Você deve incluir o conjunto completo de tag, mesmo as que não estão mudando — qualquer tag omitida da mutação será removida.

mutation updateNotebookTags {
  entityManagementUpdateNotebook(
    id: "<entity guid>"
    notebookEntity: {
      tags: [
        { key: "<key>", values: "<value>" }
        { key: "<key>", values: "<value>" }
      ]
    }
  ) {
    entity {
      name
      tags {
        key
        values
      }
    }
  }
}

Recupere o ID da sua organização

Você precisará do seu ID da organização para todas as chamadas de Blob Storage API:

query getOrgId {
  actor {
    organization {
      id
    }
  }
}

Práticas medidas

Armazene os GUIDs de entidade: Salve o entityGuid retornado das operações de criação. Você precisará disso para ler, atualizar e excluir cadernos.
Valide o JSON antes do upload: certifique-se de que a carga do seu caderno seja um JSON válido e esteja em conformidade com o esquema version antes de enviar.
Use nomes descritivos: os nomes dos notebooks devem ser exclusivos dentro de uma organização, portanto, escolha nomes que indiquem claramente o propósito (por exemplo, prod-checkout-investigation em vez de notebook-1).
Incluir todas as tags na atualização: as atualizações de tag substituem todo o conjunto de tags. Sempre leia as tags existentes antes de modificar.
Recupere rapidamente: o histórico de versões é retido por apenas 1 dia. Se você precisar de histórico de longo prazo, arquive o conteúdo do caderno em seu próprio armazenamento a cada atualização.
Proteja sua chave de API: Nunca exponha sua chave de API de Usuário em código do lado do cliente ou repositórios públicos.
Verifique os códigos de status HTTP: A API retorna 2xx para operações bem-sucedidas, 404 para não encontrado e outros códigos de status para erros.

Respostas de erro comuns

Código de status	Descrição	Solução
`400 Bad Request`	Parâmetros de solicitação inválidos, JSON malformado no corpo ou no cabeçalho `NewRelic-Entity` , ou o nome do notebook já existe nesta organização	Verifique o formato da solicitação, os valores do cabeçalho e se o nome do caderno é exclusivo em sua organização
`401 Unauthorized`	Chave de API ausente ou inválida	Verifique se sua chave de API de usuário é válida e está incluída no cabeçalho `Api-Key`
`404 Not Found`	Caderno ou versão não encontrada	Verifique se o GUID da entidade está correto.
`415 Unsupported Media Type`	Cabeçalho `Content-Type` incorreto	Usar `Content-Type: application/json`

Recursos adicionais

Visão geral dos cadernos — Como usar os cadernos na interface do New Relic
Introdução ao NerdGraph — Referência da API do GraphQL
API do Blob Storage para configurações do agente — API irmã usada por Fleet Control
Chaves de API do New Relic — Tipos de chave e gerenciamento

Esta tradução de máquina é fornecida para sua comodidade.

Usando a API do Blob Storage para cadernos

Importante

Pré-requisitos .css-21sua1{background:none;border:none;width:0;padding:0;}

Autenticação

Dica

Endpoint base

Operações de Conteúdo de Caderno

Ler o conteúdo do caderno

Atualizar o conteúdo do notebook

Excluir notebook

Recuperar versões anteriores

Operações de entidade (NerdGraph)

Listar todos os notebooks

Dica

Renomear um notebook

Atualizar tags do caderno

Importante

Recupere o ID da sua organização

Práticas medidas

Respostas de erro comuns

Recursos adicionais

Pré-requisitos