Utilisation de l'API Blob Storage pour les notebooks

Aperçu public

La Blob Storage API pour les notebooks est actuellement en version préliminaire publique. Cette fonctionnalité est fournie conformément à nos politiques de version préliminaire.

L’API New Relic Notebooks vous permet de créer, lire, mettre à jour et supprimer des notebooks par programmation, y compris le contenu complet de leurs blocs (NRQL requêtes, texte). Les notebooks sont stockés sous forme de blobs versionnés, ce qui signifie que chaque sauvegarde produit une nouvelle révision immuable que vous pouvez récupérer plus tard.

Utilisez cette API pour :

Automatiser la création de notebooks à partir de modèles d'incident, de runbooks ou de pipelines CI/CD
Synchroniser le contenu du notebook à partir du contrôle de version ou d'outils de création externes
Créer des intégrations qui remplissent les notebooks de manière programmatique lors des investigations

Important

Notebooks utiliser plusieurs API

La surface de l’API Notebooks est divisée entre deux systèmes :

Blob Storage API gère le contenu des notebooks (blocs, historique des versions)
NerdGraph gère les opérations au niveau de l'entité (liste, renommage, tags, métadonnées d'organisation)
Cette séparation est intentionnelle. Le Blob Storage API est optimisé pour le transfert de contenu de fichiers et le versioning ; NerdGraph est optimisé pour les requêtes d'entité structurées et les mutations.

Prérequis

Un compteNew Relic avec une clé d'API utilisateur
Votre ID d’organisation New Relic
Les permissions appropriées pour gérer les notebooks

Authentification

Toutes les requêtes d'API Notebooks nécessitent une authentification à l'aide d'une clé d'API utilisateur New Relic.

Générer une clé d'API :

Allez sur one.newrelic.com
Cliquez sur votre nom dans le coin supérieur droit
Select API Keys
Créez une clé User (et non une clé Browser ou clé de licence)

Inclure dans les en-têtes de requête :

bash

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

Conseil

Le Blob Storage API prend également en charge le contexte de connexion, de sorte que lors de l’appel de l’API depuis une interface utilisateur authentifiée en tant qu’utilisateur New Relic, l’en-tête Api-Key n’est pas requis.

Point de terminaison de base

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

Pour les comptes de la région UE, utilisez :

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

Opérations sur le contenu du notebook

Crée une nouvelle entité de notebook avec un contenu blob initial.

Point de terminaison

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

Paramètres de la demande [#create-params]

paramètres	Emplacement	Type de données	Description
`orgId`	Chemin	Chaîne	Obligatoire. Votre ID d'organisation New Relic .
`Api-Key`	En-tête	Chaîne	Obligatoire. Votre clé d'API utilisateur.
`Content-Type`	En-tête	Chaîne	Obligatoire. Doit être `application/json` .
`NewRelic-Entity`	En-tête	chaîne JSON	Obligatoire. Objet JSON avec les métadonnées de l’entité de notebook (voir ci-dessous).
Corps de la requête	Corps	JSON	Obligatoire. Contenu du notebook au format JSON (version + blocs).

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

Champ	Type de données	Description
`name`	Chaîne	Obligatoire. Le nom du notebook. Doit être unique dans le périmètre de l’organisation.

Format du corps du notebook [#create-body-format]

Champ	Type de données	Description
`version`	Chaîne	Version de schéma de la charge du notebook. Utilisez `"1"` .
`blocks`	Array	Liste ordonnée de blocs de notebook ( NRQL , texte, etc.). Un éventail vide crée un notebook vierge.

Champ

Type de données

Description

version

Chaîne

Version de schéma de la charge du notebook. Utilisez

"1"

blocks

Array

Liste ordonnée de blocs de notebook (

NRQL

, texte, etc.). Un éventail vide crée un notebook vierge.

Exemples de contenu d'interface utilisateur déclarative [#create-declarative-ui]

Les exemples suivants montrent comment structurer le contenu du widget de notebook en utilisant le format d’interface utilisateur déclarative.

Widget Markdown

Utilisez viz.markdown pour afficher du texte statique, des étiquettes ou des légendes de seuil à côté de vos graphiques :

{
  "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 Billboard avec la requête NRQL

Utilisez viz.billboard pour afficher une seule valeur de métrique avec des seuils optionnels codés par couleur :

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

Demande d'échantillon [#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": []
$  }'

Exemple de réponse [#create-sample-response]

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

Important

Enregistrez le entityGuid de la réponse. Vous en aurez besoin pour lire, mettre à jour et supprimer le notebook.

Récupère le dernier contenu d’un notebook.

Point de terminaison

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

Paramètres de la demande [#read-params]

paramètres

Emplacement

Type de données

Est-ce requis ?

Description

orgId

Chemin

Chaîne

Oui

Votre ID d'organisation

New Relic

entityGuid

Chemin

Chaîne

Oui

Le GUID de l’entité de notebook.

Api-Key

En-tête

Chaîne

Oui

Votre clé d'API utilisateur.

Demande d'échantillon [#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'

Exemple de réponse [#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]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Crée une nouvelle version d’un notebook existant en écrasant le contenu. La version précédente est conservée jusqu’à 1 jour (voir Récupérer les versions précédentes).

Point de terminaison

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

Paramètres de la demande [#update-params]

paramètres	Emplacement	Type de données	Est-ce requis ?	Description
`orgId`	Chemin	Chaîne	Oui	Votre ID d'organisation New Relic .
`entityGuid`	Chemin	Chaîne	Oui	Le GUID de l’entité de notebook.
`Api-Key`	En-tête	Chaîne	Oui	Votre clé d'API utilisateur.
`Content-Type`	En-tête	Chaîne	Oui	Doit être `application/json` .
Corps de la requête	Corps	JSON	Oui	Contenu du notebook mis à jour.

Demande d'échantillon [#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]
$                  }
$                ]
$              }
$            }
$          }
$        ]
$      }
$    ]
$  }'

Exemple de réponse [#update-sample-response]

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

Supprime un notebook et son contenu.

Point de terminaison

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

Paramètres de la demande [#delete-params]

paramètres

Emplacement

Type de données

Est-ce requis ?

Description

orgId

Chemin

Chaîne

Oui

Votre ID d'organisation

New Relic

entityGuid

Chemin

Chaîne

Oui

Le GUID de l'entité de notebook à supprimer.

Api-Key

En-tête

Chaîne

Oui

Votre clé d'API utilisateur.

Demande d'échantillon [#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'

Exemple de réponse [#delete-sample-response]

Renvoie HTTP 204 No Content en cas de suppression réussie.

Notebook les versions sont conservées pendant 1 jour. Pour récupérer une révision précédente, listez d’abord les versions récentes via NRQL, puis récupérez le blob spécifique.

Étape 1 — lister les 5 dernières versions

Exécutez cette requête NRQL dans le générateur de requêtes pour rassembler les ID de blob et les horodatages des 5 dernières modifications :

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

Étape 2 — Récupérer une version spécifique [#retrieve-specific-version]

Utilisez le content.id du résultat NRQL pour récupérer le contenu de cette version :

bash

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

Opérations sur les entités (NerdGraph)

Les opérations au niveau de l’entité telles que le listage, le renommage et le tag utilisent NerdGraph plutôt que Blob Storage API.

Lister tous les notebooks

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

Conseil

La création d’entité est entièrement transactionnelle, un notebook est donc immédiatement disponible via l’API. Cependant, si vous listez les notebooks via la requête actor.entitySearch legacy, il peut y avoir un court délai de propagation entre la création et l’apparition du notebook dans les résultats de la liste.

Renommer un notebook

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

Mettre à jour les tags du notebook

Important

Les mises à jour de tags sont une opération de remplacement. Vous devez inclure l’ensemble complet des tags, même ceux qui ne changent pas — tout tag omis de la mutation sera supprimé.

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

Récupérez votre identifiant d'organisation

Vous aurez besoin de l’ID de votre organisation pour tous les appels Blob Storage API :

query getOrgId {
  actor {
    organization {
      id
    }
  }
}

Meilleures pratiques

Stockez les GUID d’entité : enregistrez le entityGuid renvoyé par les opérations de création. Vous en aurez besoin pour lire, mettre à jour et supprimer des notebooks.
Valider le JSON avant le téléversement : assurez-vous que la charge de votre notebook est un JSON valide et conforme au schéma version avant l’envoi.
Utilisez des noms descriptifs : les noms de notebooks doivent être uniques au sein d’une organisation, choisissez donc des noms qui indiquent clairement leur objectif (par exemple, prod-checkout-investigation plutôt que notebook-1).
Inclure tous les tags lors de la mise à jour : les mises à jour de tags remplacent l'ensemble complet de tags. Lisez toujours les tags existants avant de les modifier.
Récupérez rapidement : l'historique des versions n'est conservé que pendant 1 jour. Si vous avez besoin d'un historique à long terme, archivez le contenu du notebook dans votre propre stockage à chaque mise à jour.
Sécurisez votre clé d'API : N'exposez jamais votre clé d'API utilisateur dans du code côté client ou des dépôts publics.
Vérifiez les codes d'état HTTP : L'API renvoie 2xx pour les opérations réussies, 404 pour non trouvé, et d'autres codes d'état pour les erreurs.

Réponses d'erreur courantes

Code d'état	Description	Solution
`400 Bad Request`	Paramètres de requête invalides, JSON malformé dans le corps ou l’en-tête `NewRelic-Entity` , ou le nom du notebook existe déjà dans cette organisation	Vérifiez le format de la requête, les valeurs d’en-tête et que le nom du notebook est unique au sein de votre organisation
`401 Unauthorized`	Clé API manquante ou invalide	Vérifiez que votre clé API utilisateur est valide et incluse dans l'en-tête `Api-Key`
`404 Not Found`	Notebook ou version introuvable	Vérifiez que le GUID de l'entité est correct
`415 Unsupported Media Type`	En-tête `Content-Type` incorrect	Utiliser `Content-Type: application/json`

Ressources supplémentaires

Aperçu des notebooks — comment utiliser les notebooks dans l’interface utilisateur New Relic
Introduction à NerdGraph — Référence de l'API GraphQL
API Blob Storage pour les configurations d’agent — API sœur utilisée par Fleet Control
Clés API New Relic — types de clés et gestion

Cette traduction automatique est fournie pour votre commodité.

Utilisation de l'API Blob Storage pour les notebooks

Aperçu public

Important

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

Authentification

Conseil

Point de terminaison de base

Opérations sur le contenu du notebook

Lire le contenu du notebook

Mettre à jour le contenu du notebook

Supprimer le notebook

Récupérer les versions précédentes

Opérations sur les entités (NerdGraph)

Lister tous les notebooks

Conseil

Renommer un notebook

Mettre à jour les tags du notebook

Important

Récupérez votre identifiant d'organisation

Meilleures pratiques

Réponses d'erreur courantes

Ressources supplémentaires

Prérequis