Tutorial NerdGraph: Criar e gerenciar dashboard

Você pode usar nossa API NerdGraph para criar e gerenciar .

Visão geral

Para obter uma introdução ao nosso recurso personalizado do painel, consulte a documentação do painel.

Ao usar o NerdGraph para configurar o painel, é útil entender que nossos painéis são considerados entidade, que possuem seus próprios IDs de entidade, semelhantes a outras coisas que consideramos entidade, como aplicativos de monitoramento, hosts e serviços.

Para saber como adicionar e configurar widgets e gráficos em um dashboard, consulte Configurar gráficos e outros widgets.

Operações CRUD dashboard

Este documento explica como usar nossa API NerdGraph para criar, ler, atualizar e excluir dashboards (CRUD). Essas operações modificam todo o dashboard.

Crie um dashboard

Um dashboard requer pelo menos uma página. Você pode criar um dashboard com uma ou mais páginas, e cada página pode ter um ou mais widgets.

Vá para o explorador NerdGraph GraphiQL em api.newrelic.com/graphiql.
Use API dashboard do NerdGraph para criar um novo dashboard e sua configuração.
Certifique-se de incluir todos os campos obrigatórios, como name, permissions e pelo menos uma página.

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

Recomendamos usar variáveis para facilitar a atualização da sua consulta. Aqui está a mesma mutação acima, mas usando variáveis:

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

E aqui estão as variáveis para usar com esta mutação:

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

Ler um dashboard

Vá para o explorador NerdGraph GraphiQL em api.newrelic.com/graphiql.
Use actor > entity() para encontrar o dashboard pelo GUID da entidade.
Use API dashboard do NerdGraph para ler o dashboard existente e sua configuração.

Neste exemplo, substitua DASHBOARD_GUID pelo GUID real do dashboard que você deseja ler:

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

Dependendo das informações que você deseja recuperar, você pode modificar os campos na consulta.

Atualizar um dashboard

Para atualizar um dashboard, você precisa fornecer a configuração completa do dashboard, incluindo todas as suas páginas e widgets, mesmo que esteja atualizando apenas um elemento. A operação de atualização é uma substituição completa do conteúdo do dashboard.

Importante

Ao atualizar um dashboard, se o GUID da página ou o ID widget não forem fornecidos, as páginas ou widgets existentes serão removidos do dashboard e substituídos pelos novos especificados na mutação.

Vá para o explorador NerdGraph GraphiQL em api.newrelic.com/graphiql.
Use API dashboard do NerdGraph para obter a configuração dashboard existente usando a leitura do dashboard pelo GUID da entidade, conforme mostrado na seção Ler um dashboard.
Modifique os campos que deseja atualizar na configuração dashboard.
Use API dashboard do NerdGraph para atualizar o dashboard existente com a configuração modificada.

Importante

Se você estiver usando Facet Linking no seu widget, ao ler o dashboard o campo será linkedEntities { guid }, mas ao atualizar o dashboard você precisará usar 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
    }
  }
}

E aqui estão as variáveis para usar com esta mutação:

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

Excluir um dashboard

Para excluir um dashboard, você precisa fornecer o GUID da entidade do dashboard que deseja excluir. Esta operação executa uma exclusão lógica que permite recuperar seu dashboard.

Vá para o explorador NerdGraph GraphiQL em api.newrelic.com/graphiql.
Use API do dashboard do NerdGraph para excluir o dashboard pelo GUID da entidade.
Confirme a exclusão marcando status e errors.

Recuperar um dashboard

Você pode recuperar um dashboard excluído anteriormente, fornecendo um GUID de entidade dashboard. A tag personalizada não pode ser recuperada.

Vá para o explorador NerdGraph GraphiQL em api.newrelic.com/graphiql.
Use API dashboard do NerdGraph para recuperar o dashboard excluído pelo GUID da entidade.
Confirme a recuperação marcando errors se houver.

Operações da página dashboard

Esta operação modifica uma página específica de um dashboard.

Atualizar uma página dashboard

Você pode atualizar uma página de um dashboard existente, dado um GUID de entidade de página de dashboard. Você precisa especificar o elemento de página dashboard completo e atualizado, desde os metadados até a configuração widget.

Vá para o explorador NerdGraph GraphiQL em api.newrelic.com/graphiql.
Use API dashboard do NerdGraph para obter a configuração dashboard existente usando a leitura do dashboard pelo GUID da entidade, conforme mostrado na seção Ler um dashboard.
Identifique e extraia a página que você deseja atualizar do dashboard.
Modifique os campos que deseja atualizar na página.
Use dashboardUpdatePage() para modificar a página.
Marque errors se houver.

Importante

Ao atualizar uma página, se os IDs widget não forem fornecidos, o widget existente será removido do dashboard e substituído pelos novos especificados na mutação.

Dica

Você pode adicionar um novo widget a uma página incluindo-o na matriz widgets sem um campo id.
Você pode remover um widget de uma página omitindo-o da matriz widgets.

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

E aqui estão as variáveis para usar com esta mutação:

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

E aqui estão as variáveis para usar com esta mutação:

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

Atualiza o widget em uma página

Você pode atualizar um conjunto de widgets existentes de uma página de dashboard, dado um GUID de entidade de página de dashboard. Você precisa especificar o conjunto de widgets a serem atualizados e sua configuração completa.

Importante

Esta operação não permite adicionar ou remover widgets de uma página. Para adicionar ou remover um widget, use a operação Atualizar uma página dashboard .

Vá para o explorador NerdGraph GraphiQL em api.newrelic.com/graphiql.
Use API dashboard do NerdGraph para obter a configuração dashboard existente usando a leitura do dashboard pelo GUID da entidade, conforme mostrado na seção Ler um dashboard.
Identifique e extraia o widget na página que você deseja atualizar do dashboard.
Modifique os campos que deseja atualizar no widget.
Use dashboardUpdateWidgetsInPage() para modificar o widget.
Marque errors se houver.

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

E aqui estão as variáveis para usar com esta mutação:

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

Outras operações

Operação	Tipo de operação GraphQL	Notas
`dashboardCreateSnapshotUrl()`	mutação	Criar operação de instantâneo da página dashboard. Você pode criar uma URL pública para uma determinada GUID de entidade de página dashboard. A página dashboard pode então ser acessada na forma de um instantâneo estático na URL pública resultante. O URL resultante será descontinuado três meses após a criação. Consulte Gerenciar instantâneos dashboard via API para obter mais informações.
`actor > dashboard > liveUrls()`	consulta	Listar todas as operações de URLs ativas. Você pode obter a lista completa de URLs ativas às quais você tem acesso. Uma URL ativa é um mecanismo que permite que você compartilhe páginas dashboard e widgets publicamente com dados atualizados ou ativos. Consulte Gerenciar URLs de gráficos ao vivo via API para obter mais informações.
`dashboardWidgetRevokeLiveUrl()`	mutação	Revogar operação de URL ativa do widget. Você pode revogar uma URL ativa de um widget criada anteriormente. Como resultado, o URL ativo ficará indisponível ao público. Consulte Gerenciar URLs de gráficos ao vivo via API para obter mais informações.
`dashboardCreateLiveUrl()`	mutação	Crie uma URL dashboard ao vivo acessível publicamente. Consulte Criar, atualizar e revogar URLs do dashboard de compartilhamento público para obter mais informações.
`dashboardUpdateLiveUrl()`	mutação	Atualizar a data de expiração de um URL dashboard ativo acessível publicamente. Consulte Criar, atualizar e revogar URLs do dashboard de compartilhamento público para obter mais informações.
`dashboardRevokeLiveUrl()`	mutação	Revogar URL dashboard ativo acessível publicamente. Consulte Criar, atualizar e revogar URLs do dashboard de compartilhamento público para obter mais informações.
`dashboardUpdateLiveUrlCreationPolicies()`	mutação	Somente um Gerenciador de domínio de autenticação pode usar essa mutação para habilitar ou desabilitar a política Live URL Creation para contas. O usuário pode criar URLs ativas para o dashboard em contas onde esta política está habilitada.

Painel entre contas

Com o NerdGraph, você pode criar consultas de dados de mais de uma conta New Relic. Você também pode criar um dashboard usando dados de várias contas adicionando IDs de contas à matriz accountIds.

Aqui está um exemplo de criação de um dashboard entre contas:

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

Limitamos os valores que você pode definir para algumas propriedades do dashboard . Isso nos permite manter o painel em bom estado e, ao mesmo tempo, aumentar sua usabilidade.

Limites dashboard

Limite	Valor
Número máximo de páginas em um dashboard	25
Comprimento máximo do nome de um dashboard	255
Comprimento máximo de uma descrição dashboard	1024

Limites de páginas dashboard

Limite	Valor
Número máximo de widgets em uma página dashboard	150
Comprimento máximo do nome de uma página dashboard	255
Comprimento máximo da descrição de uma página dashboard	1024

Limite	Valor
Comprimento máximo do título de um widget	255
Número máximo de entidades vinculadas a um widget	1
Número máximo de consultas em um widget	20
Coluna máxima de layout de um widget	12
Coluna mínima de layout de um widget	1
Linha mínima de layout de um widget	1
Largura máxima de layout de um widget	12
Largura mínima de layout de um widget	1
Altura máxima do layout de um widget	32
Altura mínima do layout de um widget	1

Erros como cidadãos de primeira classe

Todas as mutações dashboard oferecem uma maneira de solicitar erros ao serem executadas. Isso significa que você pode realizar alterações dashboard e verificar a resposta para detectar possíveis problemas esperados. Cada erro tem um tipo e uma descrição para ajudá-lo a identificar qual é a origem do problema.

Tenha em mente que estes são erros esperados dos quais estamos cientes antecipadamente. Você também deve verificar se há erros inesperados que serão retornados no campo de erros padrão do GraphQL.

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

Tutorial NerdGraph: Criar e gerenciar dashboard

Visão geral

Operações CRUD dashboard

Crie um dashboard

Dashboard com uma página, um widget e uma variável

Crie dashboard usando variáveis GraphQL

Ler um dashboard

Atualizar um dashboard

Importante

Importante

Atualizar dashboard usando variáveis GraphQL

Excluir um dashboard

Excluir um dashboard

Recuperar um dashboard

Recuperar um dashboard

Operações da página dashboard

Atualizar uma página dashboard

Importante

Dica

Atualizar uma página

Atualizar uma página adicionando um novo widget

Atualiza o widget em uma página

Importante

Outras operações

Painel entre contas

Dashboard com consulta entre contas

Limites

Limites dashboard

Limites de páginas dashboard

Limites widget

Erros como cidadãos de primeira classe

Erros como parte de cada resposta de mutação

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

Tutorial NerdGraph: Criar e gerenciar dashboard

Visão geral .css-21sua1{background:none;border:none;width:0;padding:0;}

Operações CRUD dashboard

Crie um dashboard

Crie dashboard usando variáveis GraphQL

Ler um dashboard

Atualizar um dashboard

Importante

Importante

Atualizar dashboard usando variáveis GraphQL

Excluir um dashboard

Excluir um dashboard

Recuperar um dashboard

Recuperar um dashboard

Operações da página dashboard

Atualizar uma página dashboard

Importante

Dica

Atualizar uma página

Atualizar uma página adicionando um novo widget

Atualiza o widget em uma página

Importante

Outras operações

Painel entre contas

Dashboard com consulta entre contas

Limites

Limites dashboard

Limites de páginas dashboard

Limites widget

Erros como cidadãos de primeira classe

Erros como parte de cada resposta de mutação

Visão geral