Tutoriel NerdGraph : Créer et gérer un dashboard

Vous pouvez utiliser notre API NerdGraph pour créer et gérer .

Présentation

Pour une introduction à notre fonctionnalité personnalisée de dashboard, consultez la documentation du dashboard.

Lorsque vous utilisez NerdGraph pour configurer le dashboard, il est utile de comprendre que nos dashboards sont considérés comme des entités, qui ont leurs propres identifiants d'entité, similaires à d'autres éléments que nous considérons comme des entités, comme les applications de monitoring, les hôtes et les services.

Pour savoir comment ajouter et configurer des widgets et des graphiques dans un dashboard, consultez Configurer des graphiques et d'autres widgets.

dashboard opérations CRUD

Ce document explique comment utiliser notre API NerdGraph pour créer, lire, mettre à jour et supprimer un dashboard (CRUD). Ces opérations modifient l'ensemble dashboard.

Créer un dashboard

Un dashboard nécessite au moins une page. Vous pouvez créer un dashboard avec une ou plusieurs pages, et chaque page peut avoir un ou plusieurs widgets.

Accédez à l'explorateur NerdGraph GraphiQL à l'adresse api.newrelic.com/graphiql.
Utilisez l'API dashboard de NerdGraph pour créer un nouveau dashboard et sa configuration.
Assurez-vous d'inclure tous les champs obligatoires, tels que name, permissions et au moins une page.

mutation {
  dashboardCreate(
    accountId: 1
    dashboard: {
      name: "My New Dashboard"
      description: "This is my new dashboard created via NerdGraph"
      permissions: PUBLIC_READ_WRITE
      pages: [
        {
          name: "Page 1"
          description: "This is the first page"
          widgets: [
            {
              visualization: { id: "viz.billboard" }
              layout: { column: 1, row: 1, height: 3, width: 4 }
              title: "Total Transaction Count"
              rawConfiguration: {
                nrqlQueries: [
                  { accountIds: [1], query: "SELECT count(*) FROM Transaction" }
                ]
              }
            }
          ]
        }
      ]
      variables: [
        {
          name: "nrql_variable"
          title: "countries"
          type: NRQL
          nrqlQuery: {
            accountIds: [1]
            query: "SELECT uniqueCount(countryCode) FROM PageView"
          }
          replacementStrategy: STRING
        }
      ]
    }
  ) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

Nous vous recommandons d'utiliser des variables pour faciliter la mise à jour de votre requête. Voici la même mutation que ci-dessus, mais en utilisant des variables :

mutation CreateDashboard($accountId: Int!, $dashboard: DashboardInput!) {
  dashboardCreate(accountId: $accountId, dashboard: $dashboard) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

Et voici les variables à utiliser avec cette mutation :

{
  "accountId": 1,
  "dashboard": {
    "name": "My New Dashboard",
    "description": "This is my new dashboard created via NerdGraph",
    "permissions": "PUBLIC_READ_WRITE",
    "pages": [
      {
        "name": "Page 1",
        "description": "This is the first page",
        "widgets": [
          {
            "visualization": { "id": "viz.billboard" },
            "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
            "title": "Total Transaction Count",
            "rawConfiguration": {
              "nrqlQueries": [
                {
                  "accountIds": [1],
                  "query": "SELECT count(*) FROM Transaction"
                }
              ]
            }
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "nrql_variable",
        "title": "countries",
        "type": "NRQL",
        "nrqlQuery": {
          "accountIds": [1],
          "query": "SELECT uniqueCount(countryCode) FROM PageView"
        },
        "replacementStrategy": "STRING"
      }
    ]
  }
}

Lire un dashboard

Accédez à l'explorateur NerdGraph GraphiQL à l'adresse api.newrelic.com/graphiql.
Utilisez actor > entity() pour trouver le dashboard par son entité GUID.
Utilisez l'API dashboard de NerdGraph pour lire le dashboard existant et sa configuration.

Dans cet exemple, remplacez DASHBOARD_GUID par le GUID réel du dashboard que vous souhaitez lire :

query GetDashboardEntityQuery {
  actor {
    entity(guid: "DASHBOARD_GUID") {
      ... on DashboardEntity {
        guid
        name
        description
        createdAt
        updatedAt
        owner {
          email
          userId
        }
        permissions
        pages {
          guid
          name
          description
          createdAt
          updatedAt
          widgets {
            id
            visualization {
              id
            }
            layout {
              column
              row
              height
              width
            }
            title
            linkedEntities {
              guid
            }
            rawConfiguration
          }
        }
        variables {
          name
          items {
            title
            value
          }
          defaultValues {
            value {
              string
            }
          }
          nrqlQuery {
            accountIds
            query
          }
          options {
            excluded
            ignoreTimeRange
            showApplyAction
          }
          title
          type
          isMultiSelection
          replacementStrategy
        }
      }
    }
  }
}

En fonction des informations que vous souhaitez récupérer, vous pouvez modifier les champs de la requête.

Mettre à jour un dashboard

Pour mettre à jour un dashboard, vous devez fournir la configuration complète du dashboard, y compris toutes ses pages et widgets, même si vous ne mettez à jour qu'un seul élément. L'opération de mise à jour est un remplacement complet du contenu du dashboard.

Important

Lors de la mise à jour d'un dashboard, si le GUID de la page ou l'ID widget ne sont pas fournis, les pages ou le widget existants seront supprimés du dashboard et remplacés par les nouveaux spécifiés dans la mutation.

Accédez à l'explorateur NerdGraph GraphiQL à l'adresse api.newrelic.com/graphiql.
Utilisez l'API dashboard de NerdGraph pour obtenir la configuration dashboard existante en lisant le dashboard par son entité GUID, comme indiqué dans la section Lire un dashboard.
Modifiez les champs que vous souhaitez mettre à jour dans la configuration dashboard.
Utilisez l'API dashboard de NerdGraph pour mettre à jour le dashboard existant avec la configuration modifiée.

Important

Si vous utilisez Facet Linking dans votre widget, lors de la lecture du dashboard, le champ est linkedEntities { guid } mais lors de la mise à jour du dashboard vous devez utiliser linkedEntityGuids: [ "GUID" ].

mutation UpdateDashboard(
  $guid: EntityGuid!
  $dashboard: DashboardUpdateInput!
) {
  dashboardUpdate(guid: $guid, dashboard: $dashboard) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

Et voici les variables à utiliser avec cette mutation :

{
  "guid": "DASHBOARD_GUID",
  "dashboard": {
    "name": "My Updated Dashboard",
    "description": "This is my updated dashboard created via NerdGraph",
    "permissions": "PUBLIC_READ_WRITE",
    "pages": [
      {
        "guid": "PAGE_GUID",
        "name": "Updated Page 1",
        "description": "This is the updated first page",
        "widgets": [
          {
            "id": "WIDGET_ID",
            "visualization": { "id": "viz.billboard" },
            "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
            "title": "Updated Total Transaction Count",
            "linkedEntityGuids": [],
            "rawConfiguration": {
              "nrqlQueries": [
                {
                  "accountIds": [1],
                  "query": "SELECT count(*) FROM Transaction"
                }
              ]
            }
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "nrql_variable",
        "title": "countries",
        "type": "NRQL",
        "nrqlQuery": {
          "accountIds": [1],
          "query": "SELECT uniqueCount(countryCode) FROM PageView"
        },
        "replacementStrategy": "STRING"
      }
    ]
  }
}

Supprimer un dashboard

Pour supprimer un dashboard, vous devez fournir le GUID de l'entité du dashboard que vous souhaitez supprimer. Cette opération exécute une suppression logique qui vous permet de récupérer votre dashboard.

Accédez à l'explorateur NerdGraph GraphiQL à l'adresse api.newrelic.com/graphiql.
Utilisez l'API dashboard de NerdGraph pour supprimer le dashboard par son entité GUID.
Confirmez la suppression en cochant le status et le errors.

Annuler la suppression d'un dashboard

Vous pouvez récupérer un dashboard précédemment supprimé en fonction d'un GUID d'entité dashboard. La balise personnalisée ne peut pas être récupérée.

Accédez à l'explorateur NerdGraph GraphiQL à l'adresse api.newrelic.com/graphiql.
Utilisez l'API dashboard de NerdGraph pour restaurer le dashboard par son entité GUID.
Confirmez la suppression en cochant errors le cas échéant.

Opérations de la page du dashboard

Cette opération modifie une page spécifique d'un dashboard.

Mettre à jour une page dashboard

Vous pouvez mettre à jour une page d'un dashboard existant en fonction d'une entité GUID de page dashboard. Vous devez spécifier l'élément de dashboard complet et mis à jour, de la métadonnées à configuration widget.

Accédez à l'explorateur NerdGraph GraphiQL à l'adresse api.newrelic.com/graphiql.
Utilisez l'API dashboard de NerdGraph pour obtenir la configuration dashboard existante en lisant le dashboard par son entité GUID, comme indiqué dans la section Lire un dashboard.
Identifiez et extrayez la page que vous souhaitez mettre à jour depuis le dashboard.
Modifiez les champs que vous souhaitez mettre à jour dans la page.
Utilisez dashboardUpdatePage() pour modifier la page.
Cochez errors le cas échéant.

Important

Lors de la mise à jour d'une page, si les identifiants widget ne sont pas fournis, le widget existant sera supprimé du dashboard et remplacé par les nouveaux spécifiés dans la mutation.

Conseil

Vous pouvez ajouter un nouveau widget à une page en l'incluant dans l'éventail widgets sans champ id.
Vous pouvez supprimer un widget d'une page en l'omettant de l'éventail widgets.

mutation UpdateDashboardPage(
  $pageGuid: EntityGuid!
  $page: DashboardUpdatePageInput!
) {
  dashboardUpdatePage(guid: $pageGuid, page: $page) {
    errors {
      type
      description
    }
  }
}

Et voici les variables à utiliser avec cette mutation :

{
  "guid": "PAGE_GUID",
  "page": {
    "name": "Updated Page 1",
    "description": "This is the updated first page",
    "widgets": [
      {
        "id": "WIDGET_ID",
        "visualization": { "id": "viz.billboard" },
        "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
        "title": "Updated Total Transaction Count",
        "linkedEntityGuids": [],
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM Transaction"
            }
          ]
        }
      }
    ]
  }
}

mutation UpdateDashboardPage(
  $pageGuid: EntityGuid!
  $page: DashboardUpdatePageInput!
) {
  dashboardUpdatePage(guid: $pageGuid, page: $page) {
    errors {
      type
      description
    }
  }
}

Et voici les variables à utiliser avec cette mutation :

{
  "guid": "PAGE_GUID",
  "page": {
    "name": "Updated Page 1",
    "description": "This is the updated first page",
    "widgets": [
      {
        "id": "WIDGET_ID",
        "visualization": { "id": "viz.billboard" },
        "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
        "title": "Updated Total Transaction Count",
        "linkedEntityGuids": [],
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM Transaction"
            }
          ]
        }
      },
      {
        "visualization": { "id": "viz.line" },
        "layout": { "column": 5, "row": 1, "height": 3, "width": 4 },
        "title": "New Line Chart",
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM PageView TIMESERIES"
            }
          ]
        }
      }
    ]
  }
}

Widget de mises à jour dans une page

Vous pouvez mettre à jour un ensemble de widgets existants d'une page de dashboard étant donné un GUID d'entité de page dashboard. Vous devez spécifier l'ensemble des widgets à mettre à jour et leur configuration complète.

Important

Cette opération ne permet pas d'ajouter ou de supprimer un widget d'une page. Pour ajouter ou supprimer un widget, utilisez l'opération Mettre à jour une page de dashboard .

Accédez à l'explorateur NerdGraph GraphiQL à l'adresse api.newrelic.com/graphiql.
Utilisez l'API dashboard de NerdGraph pour obtenir la configuration dashboard existante en lisant le dashboard par son entité GUID, comme indiqué dans la section Lire un dashboard.
Identifiez et extrayez le widget de la page que vous souhaitez mettre à jour depuis le dashboard.
Modifiez les champs que vous souhaitez mettre à jour dans le widget.
Utilisez dashboardUpdateWidgetsInPage() pour modifier le widget.
Cochez errors le cas échéant.

mutation UpdateWidgetsInPage(
  $pageGuid: EntityGuid!
  $widgets: [DashboardUpdateWidgetInput!]!
) {
  dashboardUpdateWidgetsInPage(guid: $pageGuid, widgets: $widgets) {
    errors {
      type
      description
    }
  }
}

Et voici les variables à utiliser avec cette mutation :

{
  "guid": "PAGE_GUID",
  "widgets": [
    {
      "id": "WIDGET_ID",
      "visualization": { "id": "viz.billboard" },
      "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
      "title": "Updated Total Transaction Count",
      "linkedEntityGuids": [],
      "rawConfiguration": {
        "nrqlQueries": [
          {
            "accountIds": [1],
            "query": "SELECT count(*) FROM Transaction"
          }
        ]
      }
    }
  ]
}

Autres opérations

Opération	Type d'opération GraphQL	Remarques
`dashboardCreateSnapshotUrl()`	mutation	Créer une opération d'instantané de page dashboard. Vous pouvez créer une URL publique pour une entité GUID de page dashboard donnée. La page dashboard est ensuite accessible sous la forme d’un instantané statique dans l’URL publique résultante. L'URL résultante sera obsolète trois mois après sa création. Consultez Gérer les instantanés dashboard via l'API pour plus d'informations.
`actor > dashboard > liveUrls()`	requête	Répertoriez toutes les opérations d'URL en direct. Vous pouvez obtenir la liste complète des URL en direct auxquelles vous avez accès. Une URL en direct est un mécanisme qui vous permet de partager publiquement des pages dashboard et des widgets avec des données à jour ou en direct. Consultez Gérer les URL des graphiques en direct via l'API pour plus d'informations.
`dashboardWidgetRevokeLiveUrl()`	mutation	Révoquer l'opération d'URL en direct du widget. Vous pouvez révoquer une URL en direct précédemment créée d'un widget. Par conséquent, l’URL en direct ne sera plus disponible au public. Consultez Gérer les URL des graphiques en direct via l'API pour plus d'informations.
`dashboardCreateLiveUrl()`	mutation	Créez une URL dashboard en direct accessible au public. Pour plus d'informations, consultez Créer, mettre à jour et révoquer les URL du dashboard de partage public.
`dashboardUpdateLiveUrl()`	mutation	Mettre à jour la date d’expiration d’une URL dashboard en direct accessible au public. Pour plus d'informations, consultez Créer, mettre à jour et révoquer les URL du dashboard de partage public.
`dashboardRevokeLiveUrl()`	mutation	Révoquer l'URL dashboard en direct accessible au public. Pour plus d'informations, consultez Créer, mettre à jour et révoquer les URL du dashboard de partage public.
`dashboardUpdateLiveUrlCreationPolicies()`	mutation	Seul un gestionnaire de domaine d’authentification peut utiliser cette mutation pour activer ou désactiver la politique Live URL Creation pour les comptes. L'utilisateur peut créer des URL en direct pour le dashboard dans les comptes où cette politique est activée.

Dashboards multi-comptes

Avec NerdGraph, vous pouvez créer des requêtes de données à partir de plusieurs comptes New Relic . Vous pouvez également créer un dashboard à l'aide de données provenant de plusieurs comptes en ajoutant des identifiants de compte à l'éventail accountIds.

Voici un exemple de création d'un dashboard multi-comptes :

mutation {
  dashboardCreate(
    accountId: 1
    dashboard: {
      name: "Cross account queries - NerdGraph API - Cross Account Test1"
      description: null
      permissions: PUBLIC_READ_WRITE
      pages: [
        {
          name: "Page 1"
          description: null
          widgets: [
            {
              visualization: { id: "viz.billboard" }
              layout: { column: 1, row: 1, height: 3, width: 4 }
              title: "Cross Account Total Transaction Count"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.pie" }
              layout: { column: 5, row: 1, height: 3, width: 4 }
              title: "Cross Account Pie"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId()"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.line" }
              layout: { column: 9, row: 1, height: 3, width: 4 }
              title: "Cross Account Line"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId() TIMESERIES"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
          ]
        }
      ]
    }
  ) {
    errors {
      description
      type
    }
  }
}

Limites

Nous avons limité les valeurs que vous pouvez définir pour certaines propriétés dashboard . Cela nous permet de maintenir le dashboard en bon état tout en améliorant sa convivialité.

Limites du dashboard

Limite	Valeur
Nombre maximal de pages dans un dashboard	25
Longueur maximale d'un nom dashboard	255
Longueur maximale d'une description dashboard	1024

Limites de la page du dashboard

Limite	Valeur
Nombre maximal de widgets dans une page dashboard	150
Longueur maximale d'un nom de page dashboard	255
Longueur maximale d'une description de page dashboard	1024

Limite	Valeur
Longueur maximale d'un titre de widget	255
Nombre maximal d'entités liées à un widget	1
Nombre maximal de requêtes dans un widget	20
Colonne de disposition maximale d'un widget	12
Colonne de disposition minimale d'un widget	1
Ligne de disposition minimale d'un widget	1
Largeur de mise en page maximale d'un widget	12
Largeur minimale de mise en page d'un widget	1
Hauteur de mise en page maximale d'un widget	32
Hauteur minimale de mise en page d'un widget	1

Les erreurs des citoyens de première classe

Toutes les mutations dashboard offrent un moyen de demander des erreurs lors de leur exécution. Cela signifie que vous pouvez effectuer vos mutations dashboard et vérifier la réponse afin de détecter les problèmes potentiels attendus. Chaque erreur a un type et une description pour vous aider à identifier la source du problème.

Gardez à l'esprit qu'il s'agit d'erreurs attendues dont nous sommes conscients à l'avance. Vous devez également vérifier les erreurs inattendues qui seront renvoyées dans le champ d’erreurs GraphQL standard.

Cette traduction automatique est fournie pour votre commodité.

Tutoriel NerdGraph : Créer et gérer un dashboard

Présentation

dashboard opérations CRUD

Créer un dashboard

Dashboard avec une page, un widget et une variable

Créer dashboard à l'aide de variables GraphQL

Lire un dashboard

Mettre à jour un dashboard

Important

Important

Mettre à jour dashboard à l'aide de variables GraphQL

Supprimer un dashboard

Supprimer un dashboard

Annuler la suppression d'un dashboard

Annuler la suppression d'un dashboard

Opérations de la page du dashboard

Mettre à jour une page dashboard

Important

Conseil

Mettre à jour une page

Mettre à jour une page en ajoutant un nouveau widget

Widget de mises à jour dans une page

Important

Autres opérations

Dashboards multi-comptes

Dashboard avec requête inter-comptes

Limites

Limites du dashboard

Limites de la page du dashboard

Limites des widgets

Les erreurs des citoyens de première classe

Des erreurs dans chaque réponse à une mutation

Cette traduction automatique est fournie pour votre commodité.

Tutoriel NerdGraph : Créer et gérer un dashboard

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

dashboard opérations CRUD

Créer un dashboard

Créer dashboard à l'aide de variables GraphQL

Lire un dashboard

Mettre à jour un dashboard

Important

Important

Mettre à jour dashboard à l'aide de variables GraphQL

Supprimer un dashboard

Supprimer un dashboard

Annuler la suppression d'un dashboard

Annuler la suppression d'un dashboard

Opérations de la page du dashboard

Mettre à jour une page dashboard

Important

Conseil

Mettre à jour une page

Mettre à jour une page en ajoutant un nouveau widget

Widget de mises à jour dans une page

Important

Autres opérations

Dashboards multi-comptes

Dashboard avec requête inter-comptes

Limites

Limites du dashboard

Limites de la page du dashboard

Limites des widgets

Les erreurs des citoyens de première classe

Des erreurs dans chaque réponse à une mutation

Présentation