Uso de la API de Blob Storage para notebooks

Vista previa pública

El Blob Storage API para notebooks está actualmente en vista previa pública. Esta característica se proporciona de acuerdo con nuestras políticas de prelanzamiento.

La API Notebooks de New Relic te permite crear, leer, actualizar y eliminar cuadernos de forma programática, incluido el contenido completo de sus bloques (NRQL consultas, texto). Los cuadernos se almacenan como blobs versionados, lo que significa que cada guardado produce una nueva revisión inmutable que puedes recuperar más tarde.

Utilice esta API para:

Automatizar la creación de notebooks a partir de plantillas de incidentes, runbooks o pipelines de CI/CD
Sincronizar el contenido del notebook desde el control de versiones o herramientas de creación externas
Cree integraciones que completen los notebooks de forma programática durante las investigaciones

Importante

Notebooks usar múltiples API

La superficie de la API de Notebooks se divide entre dos sistemas:

Blob Storage API maneja el contenido del cuaderno (bloques, historial de versiones)
NerdGraph maneja operaciones a nivel de entidad (lista, cambio de nombre, etiquetas, metadatos de organización)
Esta separación es por diseño. El Blob Storage API está optimizado para la transferencia de contenido de archivos y el control de versiones; NerdGraph está optimizado para consultas y mutaciones de entidades estructuradas.

Requisitos previos

Una cuenta deNew Relic con una clave de API de usuario
Tu ID de organización de New Relic
Los permisos adecuados para administrar notebooks

Autenticación

Todas las solicitudes a la API de Notebooks requieren autenticación mediante una clave de API de usuario de New Relic.

Generar una clave de API:

Vaya a one.newrelic.com
Haga clic en su nombre en la esquina superior derecha
Seleccionar API Keys
Crea una clave de User (no una clave de Browser o clave de licencia)

Incluir en los encabezados de la solicitud:

bash

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

Sugerencia

El Blob Storage API también admite el contexto de inicio de sesión, por lo que al llamar a la API desde una UI autenticada como usuario de New Relic, no se requiere el encabezado Api-Key.

Endpoint base

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

Para las cuentas de la región de la UE, use:

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

Operaciones de contenido de notebooks

Crea una nueva entidad de cuaderno con contenido blob inicial.

Extremo

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

Solicitar parámetro [#create-params]

Parámetro	Ubicación	Tipo de datos	Descripción
`orgId`	Camino	Cadena	Obligatorio. Tu ID de organización de New Relic .
`Api-Key`	Encabezamiento	Cadena	Obligatorio. Tu clave de API de usuario.
`Content-Type`	Encabezamiento	Cadena	Obligatorio. Debe ser `application/json` .
`NewRelic-Entity`	Encabezamiento	cadena JSON	Obligatorio. Objeto JSON con metadatos de la entidad de notebook (ver a continuación).
Cuerpo de la solicitud	Cuerpo	JSON	Obligatorio. Contenido del notebook en formato JSON (versión + bloques).

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

Campo	Tipo de datos	Descripción
`name`	Cadena	Obligatorio. El nombre del notebook. Debe ser único dentro del alcance de la organización.

Formato del cuerpo del cuaderno [#create-body-format]

Campo	Tipo de datos	Descripción
`version`	Cadena	Versión del esquema de la carga del notebook. Utilice `"1"` .
`blocks`	Matriz	Lista ordenada de bloques de notebook ( NRQL , texto, etc.). Una matriz vacía crea un notebook en blanco.

Campo

Tipo de datos

Descripción

version

Cadena

Versión del esquema de la carga del notebook. Utilice

"1"

blocks

Matriz

Lista ordenada de bloques de notebook (

NRQL

, texto, etc.). Una matriz vacía crea un notebook en blanco.

Ejemplos de contenido de UI declarativa [#create-declarative-ui]

Los siguientes ejemplos muestran cómo estructurar el contenido del widget del notebook usando el formato de UI declarativa.

Widget de Markdown

Use viz.markdown para representar texto estático, etiquetas o leyendas de umbral junto a sus 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 con la consulta NRQL

Usa viz.billboard para mostrar un único valor de métrica con umbrales opcionales codificados por colores:

{
  "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" }
    }
  }
}

Solicitud de muestra [#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": []
$  }'

Ejemplo de respuesta [#create-sample-response]

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

Importante

Guarde el entityGuid de la respuesta. Lo necesitará para leer, actualizar y eliminar el notebook.

Recupera el contenido más reciente de un notebook.

Extremo

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

Solicitar parámetro [#read-params]

Parámetro

Ubicación

Tipo de datos

¿Es requerido?

Descripción

orgId

Camino

Cadena

Sí

Tu ID de organización de

New Relic

entityGuid

Camino

Cadena

Sí

El GUID de la entidad del notebook.

Api-Key

Encabezamiento

Cadena

Sí

Tu clave de API de usuario.

Solicitud de muestra [#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'

Ejemplo de respuesta [#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]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Crea una nueva versión de un notebook existente sobrescribiendo el contenido. La versión anterior se conserva hasta por 1 día (consulte Recuperar versiones anteriores).

Extremo

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

Solicitar parámetro [#update-params]

Parámetro	Ubicación	Tipo de datos	¿Es requerido?	Descripción
`orgId`	Camino	Cadena	Sí	Tu ID de organización de New Relic .
`entityGuid`	Camino	Cadena	Sí	El GUID de la entidad del notebook.
`Api-Key`	Encabezamiento	Cadena	Sí	Tu clave de API de usuario.
`Content-Type`	Encabezamiento	Cadena	Sí	Debe ser `application/json` .
Cuerpo de la solicitud	Cuerpo	JSON	Sí	Contenido del notebook actualizado.

Solicitud de muestra [#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]
$                  }
$                ]
$              }
$            }
$          }
$        ]
$      }
$    ]
$  }'

Ejemplo de respuesta [#update-sample-response]

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

Elimina un notebook y su contenido.

Extremo

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

Solicitar parámetro [#delete-params]

Parámetro

Ubicación

Tipo de datos

¿Es requerido?

Descripción

orgId

Camino

Cadena

Sí

Tu ID de organización de

New Relic

entityGuid

Camino

Cadena

Sí

El GUID de la entidad del notebook a eliminar.

Api-Key

Encabezamiento

Cadena

Sí

Tu clave de API de usuario.

Solicitud de muestra [#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'

Ejemplo de respuesta [#delete-sample-response]

Devuelve HTTP 204 No Content tras una eliminación exitosa.

Notebook las versiones se retienen durante 1 día. Para recuperar una revisión anterior, primero liste las versiones recientes a través de NRQL, luego recupere el blob específico.

Paso 1 — listar las últimas 5 versiones

Ejecute esta consulta NRQL en el generador de consultas para recopilar los ID de blob y los timestamp de los últimos 5 cambios:

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

Paso 2 — recuperar una versión específica [#retrieve-specific-version]

Usa el content.id del resultado de NRQL para obtener el contenido de esa versión:

bash

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

Operaciones de entidad (NerdGraph)

Las operaciones a nivel de entidad, como listar, renombrar y asignar etiquetas, usan NerdGraph en lugar de Blob Storage API.

Listar todos los notebooks

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

Sugerencia

La creación de la entidad es completamente transaccional, por lo que un notebook está disponible de inmediato a través de la API. Sin embargo, si enumera los notebooks a través de la consulta legacy actor.entitySearch, puede haber un breve retraso de propagación entre la creación y la aparición del notebook en los resultados de la lista.

Renombrar un notebook

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

Actualizar las etiquetas del notebook

Importante

Las actualizaciones de etiquetas son una operación de reemplazo. Debes incluir el conjunto completo de etiquetas, incluso las que no cambian — cualquier etiqueta omitida de la mutación será eliminada.

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

Recuperar el ID de su organización

Necesitará el ID de su organización para todas las llamadas de Blob Storage API:

query getOrgId {
  actor {
    organization {
      id
    }
  }
}

Mejores practicas

Almacena los GUID de la entidad: guarda el entityGuid devuelto por las operaciones de creación. Lo necesitarás para leer, actualizar y eliminar cuadernos.
Validar JSON antes de cargarlo: asegúrese de que la carga de su notebook sea un JSON válido y cumpla con el esquema version antes de enviarlo.
Use nombres descriptivos: los nombres de los notebooks deben ser únicos dentro de una organización, así que elija nombres que indiquen claramente su propósito (por ejemplo, prod-checkout-investigation en lugar de notebook-1).
Incluye todas las etiquetas en la actualización: las actualizaciones de etiquetas reemplazan el conjunto completo de etiquetas. Lee siempre las etiquetas existentes antes de mutar.
Recuperación rápida: el historial de versiones se conserva durante solo 1 día. Si necesita un historial a largo plazo, archive el contenido del notebook en su propio almacenamiento en cada actualización.
Proteja su clave de API: Nunca exponga su clave de API de usuario en el código del lado del cliente ni en repositorios públicos.
Verifique los códigos de estado HTTP: La API devuelve 2xx para operaciones exitosas, 404 para no encontrado y otros códigos de estado para errores.

Respuestas de error comunes

Código de estado	Descripción	Solución
`400 Bad Request`	Parámetros de solicitud no válidos, JSON mal formado en el cuerpo o en el encabezado `NewRelic-Entity` , o el nombre del cuaderno ya existe en esta organización	Verifica el formato de la solicitud, los valores del encabezado y que el nombre del cuaderno sea único dentro de tu organización
`401 Unauthorized`	Clave de API faltante o inválida	Verifica que tu clave de API de usuario sea válida y esté incluida en el encabezado `Api-Key`
`404 Not Found`	Notebook o versión no encontrada	Verifica que el GUID de la entidad sea correcto
`415 Unsupported Media Type`	Encabezado `Content-Type` incorrecto	Usar `Content-Type: application/json`

Recursos adicionales

Descripción general de notebooks — cómo usar notebooks en la UI de New Relic
Introducción a NerdGraph — referencia de la API de GraphQL
API de Blob Storage para las configuraciones del agente — API hermana utilizada por Fleet Control
Claves de API de New Relic — tipos de claves y gestión

Te ofrecemos esta traducción automática para facilitar la lectura.

Uso de la API de Blob Storage para notebooks

Vista previa pública

Importante

Requisitos previos .css-21sua1{background:none;border:none;width:0;padding:0;}

Autenticación

Sugerencia

Endpoint base

Operaciones de contenido de notebooks

Leer el contenido del notebook

Actualizar el contenido del notebook

Eliminar cuaderno

Recuperar versiones anteriores

Operaciones de entidad (NerdGraph)

Listar todos los notebooks

Sugerencia

Renombrar un notebook

Actualizar las etiquetas del notebook

Importante

Recuperar el ID de su organización

Mejores practicas

Respuestas de error comunes

Recursos adicionales

Requisitos previos