Migrar da API REST v2 para o NerdGraph

Este guia auxilia na migração da API REST v2 da New Relic para a API GraphQL do NerdGraph. O NerdGraph é a API recomendada da New Relic, que oferece um único endpoint unificado, busca precisa de dados e tipagem forte.

Importante

A API REST v2 da New Relic (incluindo os endpoints de alertas) e a API v0 de implantação chegarão ao fim da vida útil em 31 de julho de 2027. Após essa data, esses endpoints não estarão mais disponíveis. Migre as integrações para o NerdGraph antes dessa data.

Dica

As consultas neste guia são um ponto de partida — não substitutos diretos para os endpoints da REST v2. Com qualquer consulta base, é possível omitir campos desnecessários ou adicionar campos que podem não estar disponíveis na chamada REST original. Em alguns casos, como coleções de objetos "outline" em oposição a campos de detalhes, a correspondência exata de campos não é possível diretamente.

Antes de você começar

Obter uma chave de API do usuário

É possível reutilizar a chave de API do usuário já utilizada para fazer chamadas REST, mas observe que a API REST v2 fazia suposições com base na conta usada para criar a chave de API do usuário. O NerdGraph não faz suposições semelhantes.

Endpoints do NerdGraph

https://api.newrelic.com/graphql
https://api.eu.newrelic.com/graphql

Explorar interativamente

Use o explorador da API NerdGraph para criar e testar consultas com documentação embutida e preenchimento automático.

GUIDs da Entidade

O NerdGraph normalmente usa GUIDs de entidade (identificadores exclusivos globais) em vez de IDs numéricos do aplicativo. É possível pesquisar um GUID de entidade a partir de um ID do aplicativo da API REST usando uma consulta de pesquisa de entidade (consulte Aplicativos). O Monitoramento de Alterações ainda pode ser feito apenas com um appId.

Autenticação

API REST v2:

bash

$curl -X GET 'https://api.newrelic.com/v2/applications.json' \
>  -H "Api-Key: $USER_API_KEY"

NerdGraph:

bash

$curl -X POST 'https://api.newrelic.com/graphql' \
>  -H 'Content-Type: application/json' \
>  -H "Api-Key: $USER_API_KEY" \
>  -d '{"query": "{ actor { user { email } } }"}'

Para obter mais informações, consulte Introdução ao NerdGraph.

Principais Diferenças

Recurso	API REST v2	NerdGraph (GraphQL)
Protocolo	Múltiplos endpoints REST	Endpoint GraphQL Único
Autenticação	Chave de API do usuário (cabeçalho `Api-Key` ou `X-Api-Key` )	Chave de API do usuário (cabeçalho `Api-Key` ), identidades do sistema
Busca de dados	Formatos de resposta fixos	Formato da resposta determinado pela consulta fornecida
Identificador	IDs numéricos (por ex., ID do aplicativo)	Inteiros para contas, GUIDs de entidade para aplicativos, etc.
Listas vs. detalhe	Objetos completos retornados em endpoints de lista	Muitos campos de coleção incluem apenas um objeto "Outline". Pode ser necessário consultar um único item para obter mais detalhes.
Paginação	Baseado em página ( `?page=N` )	Paginação baseada em cursor
Dados métricos	Endpoints de métrica dedicados	Consultas NRQL via `actor.nrql` ou `actor.account.nrql`
Limites de taxa	Limites por chave	Limites de simultaneidade e taxas de transferência

Aplicativos

Listar aplicativos

API REST v2: GET /v2/applications.json

NerdGraph: use entitySearch para encontrar aplicativos APM. Adicione accountId = YOUR_ACCOUNT_ID para limitar os resultados a uma conta específica. Não é necessário fornecer um accountId, e é possível pesquisar um aplicativo específico adicionando AND domainId = <ID of app>.

{
  actor {
    entitySearch(
      query: "domain = 'APM' AND type = 'APPLICATION' AND accountId = YOUR_ACCOUNT_ID"
    ) {
      results {
        entities {
          guid
          name
          reporting
          alertSeverity
          ... on ApmApplicationEntityOutline {
            applicationId
            language
            apmSummary {
              responseTimeAverage
              throughput
              errorRate
              apdexScore
            }
          }
        }
        nextCursor
      }
    }
  }
}

Para filtrar por nome (equivalente a filter[name]):

{
  actor {
    entitySearch(
      query: "domain = 'APM' AND type = 'APPLICATION' AND accountId = YOUR_ACCOUNT_ID AND name LIKE 'MyApp'"
    ) {
      results {
        entities {
          guid
          name
        }
      }
    }
  }
}

Dica

A API REST GET /v2/applications.json pode retornar aplicativos que não relatam mais dados ou que foram excluídos. O NerdGraph entitySearch retorna apenas entidades que estão indexadas na plataforma de entidade. Se houver menos resultados do NerdGraph, aplicativos que não relatam dados ou inativos há muito tempo são a causa provável.

Mostrar aplicativo

API REST v2: GET /v2/applications/{id}.json

NerdGraph: buscar por GUID da entidade:

{
  actor {
    entity(guid: "YOUR_ENTITY_GUID") {
      name
      alertSeverity
      reporting
      ... on ApmApplicationEntity {
        applicationId
        language
        apmSummary {
          responseTimeAverage
          throughput
          errorRate
          apdexScore
          hostCount
          instanceCount
        }
        settings {
          apdexTarget
          serverSideConfig
        }
      }
    }
  }
}

Dica

Para encontrar o GUID da entidade a partir de um ID do aplicativo da API REST:

{
  actor {
    entitySearch(query: "domainId = 'APP_ID' AND domain = 'APM'") {
      results {
        entities {
          guid
          name
        }
      }
    }
  }
}

Atualizar configurações do aplicativo

API REST v2: PUT /v2/applications/{id}.json

NerdGraph:

mutation {
  agentApplicationSettingsUpdate(
    guid: "YOUR_ENTITY_GUID"
    settings: {
      alias: "My App Display Name"
      apmConfig: { apdexTarget: 0.5, useServerSideConfig: true }
    }
  ) {
    alias
    guid
    apmSettings {
      apdexTarget
      useServerSideConfig
    }
  }
}

Dica

Há muitas outras configurações disponíveis. Consulte a documentação embutida no NerdGraph API Explorer para obter uma lista completa.

Excluir aplicativo

API REST v2: DELETE /v2/applications/{id}.json

NerdGraph:

mutation {
  agentApplicationDelete(guid: "YOUR_ENTITY_GUID") {
    success
  }
}

Para obter mais informações, consulte Tutorial de Entidades do NerdGraph e Tutorial de Configurações do APM.

Dados de métrica do aplicativo

Listar nomes métricos

API REST v2: GET /v2/applications/{app_id}/metrics.json

NerdGraph: use uma consulta NRQL para listar os nomes de métricas disponíveis:

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT uniques(metricTimesliceName) FROM Metric WHERE appId = YOUR_APP_ID AND newrelic.timeslice.value IS NOT NULL SINCE 30 MINUTES AGO LIMIT MAX"
    ) {
      results
    }
  }
}

Ou filtrar por nome do aplicativo:

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT uniques(metricTimesliceName) FROM Metric WHERE appName = 'YourAppName' AND newrelic.timeslice.value IS NOT NULL SINCE 30 MINUTES AGO LIMIT MAX"
    ) {
      results
    }
  }
}

Dica

A API REST retorna todos os nomes de métricas historicamente conhecidos, independentemente da janela de tempo, juntamente com os tipos de valor disponíveis para cada métrica (por exemplo, average_response_time, call_count, calls_per_minute). A consulta NRQL retorna apenas métricas que relataram dados dentro da janela SINCE — estenda-a (por exemplo, SINCE 1 WEEK AGO) para descobrir mais nomes de métricas. O NerdGraph não possui um equivalente para listar tipos de valor por métrica. Em vez disso, use a tabela de mapeamento de resumo abaixo (ou siga o link para mais mapeamentos) para traduzir os nomes de valor da API REST para funções NRQL — todas as métricas de timeslice suportam o mesmo conjunto de funções de agregação.

Obter dados métricos

API REST v2: GET /v2/applications/{app_id}/metrics/data.json?names[]=HttpDispatcher&values[]=average_call_time&values[]=call_count

NerdGraph: use consultas NRQL com as funções de agregação apropriadas. Adicione TIMESERIES para obter pontos de dados por intervalo (equivalente à matriz de fatia de tempo da API REST):

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT count(newrelic.timeslice.value) AS call_count, average(newrelic.timeslice.value) * 1000 AS average_call_time FROM Metric WHERE appId = YOUR_APP_ID AND metricTimesliceName = 'HttpDispatcher' SINCE 30 MINUTES AGO TIMESERIES"
    ) {
      results
    }
  }
}

Dica

Sem TIMESERIES, o NRQL retorna um único valor agregado para todo o intervalo de tempo. A API REST retorna frações de tempo por minuto por padrão. Adicione TIMESERIES 1 minute para corresponder à granularidade padrão da API REST.

Mapeamento do valor da métrica da API REST para a função NRQL

Valor da API REST	Função NRQL
`average_response_time`	`average(newrelic.timeslice.value) * 1000`
`calls_per_minute`	`rate(count(newrelic.timeslice.value), 1 minute)`
`call_count`	`count(newrelic.timeslice.value)`
`min_response_time`	`min(newrelic.timeslice.value) * 1000`
`max_response_time`	`max(newrelic.timeslice.value) * 1000`
`average_exclusive_time`	`average(newrelic.timeslice.value['totalExclusive'] / newrelic.timeslice.value['count']) * 1000`
`average_value`	`average(newrelic.timeslice.value)`
`total_call_time_per_minute`	`rate(sum(newrelic.timeslice.value), 1 minute)`
`requests_per_minute`	`rate(count(newrelic.timeslice.value), 1 minute)`
`standard_deviation`	`stddev(newrelic.timeslice.value) * 1000`
`error_count`	`count(newrelic.timeslice.value)`
`errors_per_minute`	`rate(count(newrelic.timeslice.value), 1 minute)`
`throughput`	`rate(count(newrelic.timeslice.value), 1 second)`
`as_percentage`	`average(newrelic.timeslice.value) * 100`

Para obter mais informações, consulte Introdução à API de Métrica, Guia de Consulta de Métrica e Migrar Consultas de Métrica de Fração de Tempo para NRQL.

Hosts e instâncias do aplicativo

Listar hosts do aplicativo

API REST v2: GET /v2/applications/{app_id}/hosts.json

NerdGraph: usar NRQL para consultar dados no nível do host:

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT uniqueCount(host) FROM Transaction WHERE appName = 'YourAppName' SINCE 1 hour ago FACET host"
    ) {
      results
    }
  }
}

Dica

A abordagem FROM Transaction retorna apenas os hosts que processaram transações dentro da janela SINCE.

Dados de métrica de host/instância do aplicativo

API REST v2: GET /v2/applications/{app_id}/hosts/{host_id}/metrics/data.json

NerdGraph: filtrar consultas NRQL por host ou instância do agente:

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT average(newrelic.timeslice.value) * 1000 AS avg_response_time FROM Metric WHERE appName = 'YourAppName' AND host = 'your-host.example.com' AND metricTimesliceName = 'HttpDispatcher' SINCE 30 MINUTES AGO"
    ) {
      results
    }
  }
}

Implantação

Listar implantações

API REST v2: GET /v2/applications/{app_id}/deployments.json

NerdGraph: consulta de implantações via NRQL:

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT eventType(), deploymentId or changeTrackingId AS 'id', * FROM ChangeTrackingEvent, Deployment WHERE (eventType() = 'Deployment' OR (eventType() = 'ChangeTrackingEvent' AND category = 'Deployment')) AND entity.guid = 'YOUR_ENTITY_GUID' SINCE 1 WEEK AGO LIMIT 100"
    ) {
      results
    }
  }
}

Criar implantação

API REST v2: POST /v2/applications/{app_id}/deployments.json

NerdGraph: use a mutação changeTrackingCreateEvent.

mutation {
  changeTrackingCreateEvent(
    changeTrackingEvent: {
      entitySearch: {
        query: "name = 'YOUR_ENTITY_NAME' and accountId = YOUR_ACCOUNT_ID"
      }
      categoryAndTypeData: {
        kind: { category: "DEPLOYMENT", type: "BASIC" }
        categoryFields: {
          deployment: {
            version: "1.2.3"
            changelog: "Fixed authentication bug"
            commit: "abc123def456"
          }
        }
      }
      description: "Production deployment of auth fix"
      shortDescription: "user deployer@example.com deployed version 1.2.3 to environment: commerce_prod"
      user: "deployer@example.com"
      customAttributes: {
        cloud_vendor: "vendor_name"
        region: "us-east-1"
        environment: "commerce_prod"
      }
    }
  ) {
    changeTrackingEvent {
      changeTrackingId
      timestamp
      user
      description
      entity {
        guid
        domain
        name
      }
      customAttributes
    }
  }
}

Dica

Como algumas outras operações do NerdGraph, changeTrackingCreateEvent aceita um entitySearch, tornando-o o caminho de migração mais fácil da API REST. É possível pesquisar por name, bem como por entityGuid, se o tiver. Consulte Rastrear Alterações Usando o NerdGraph para obter todos os campos disponíveis.

Excluir implantação

API REST v2: DELETE /v2/applications/{app_id}/deployments/{id}.json

NerdGraph: não há mutação de exclusão direta para implantações no NerdGraph. Os registros de implantação são eventos de Monitoramento de Alterações imutáveis.

Para obter mais informações, consulte Rastrear alterações usando o NerdGraph.

Transação principal

Listar transações principais

API REST v2: GET /v2/key_transactions.json

NerdGraph: use a pesquisa de entidade com o tipo KEY_TRANSACTION. Adicione accountId para limitar o escopo a uma conta específica:

{
  actor {
    entitySearch(
      query: "type = 'KEY_TRANSACTION' AND accountId = YOUR_ACCOUNT_ID"
    ) {
      results {
        entities {
          guid
          name
          reporting
          alertSeverity
        }
        nextCursor
      }
    }
  }
}

Dica

O tipo KeyTransactionEntityOutline não inclui métricas de resumo, como tempo de resposta ou taxas de transferência diretamente. Para obter dados de desempenho para uma transação principal, use a consulta de entidade completa abaixo ou execute uma consulta NRQL no nome da métrica da transação principal.

Mostrar transação principal

API REST v2: GET /v2/key_transactions/{id}.json

NerdGraph:

{
  actor {
    entity(guid: "KEY_TRANSACTION_ENTITY_GUID") {
      name
      ... on KeyTransactionEntity {
        apdexTarget
        metricName
        application {
          guid
          entity {
            name
          }
        }
      }
    }
  }
}

Para obter métricas de desempenho equivalentes (por exemplo, taxas de transferência), use uma consulta NRQL com o nome da métrica da transação principal:

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT average(newrelic.timeslice.value) * 1000 AS responseTimeAverage, rate(count(newrelic.timeslice.value), 1 minute) AS throughput FROM Metric WHERE entity.guid = 'ENTITY_GUID' SINCE 30 minutes AGO TIMESERIES"
    ) {
      results
    }
  }
}

Aplicativo móvel

Listar aplicativos mobile

API REST v2: GET /v2/mobile_applications.json

NerdGraph:

{
  actor {
    entitySearch(
      query: "domain = 'MOBILE' AND type = 'APPLICATION' AND accountId = YOUR_ACCOUNT_ID"
    ) {
      results {
        entities {
          guid
          name
          reporting
          ... on MobileApplicationEntityOutline {
            applicationId
            mobileSummary {
              appLaunchCount
              crashCount
              crashRate
              httpErrorRate
              httpRequestCount
              httpRequestRate
              httpResponseTimeAverage
              mobileSessionCount
              networkFailureRate
              usersAffectedCount
            }
          }
        }
        nextCursor
      }
    }
  }
}

Mostrar aplicativo mobile

API REST v2: GET /v2/mobile_applications/{id}.json

NerdGraph:

{
  actor {
    entity(guid: "MOBILE_APP_ENTITY_GUID") {
      name
      ... on MobileApplicationEntity {
        applicationId
        mobileSummary {
          appLaunchCount
          crashCount
          crashRate
          httpErrorRate
          httpRequestCount
          httpResponseTimeAverage
          mobileSessionCount
          networkFailureRate
          usersAffectedCount
        }
      }
    }
  }
}

Dica

Para encontrar o GUID de entidade a partir de um ID do aplicativo mobile da API REST:

{
  actor {
    entitySearch(query: "domainId = 'MOBILE_APP_ID' AND domain = 'MOBILE'") {
      results {
        entities {
          guid
          name
        }
      }
    }
  }
}

Dados de métrica de aplicativo móvel

API REST v2: GET /v2/mobile_applications/{id}/metrics/data.json

NerdGraph: use NRQL para consultar dados de métrica móvel:

{
  actor {
    nrql(
      accounts: [YOUR_ACCOUNT_ID]
      query: "SELECT average(duration) FROM Mobile WHERE appName = 'YourMobileApp' SINCE 1 HOUR AGO TIMESERIES"
    ) {
      results
    }
  }
}

Criar aplicativo mobile

API REST v2: POST /v2/mobile_applications.json

NerdGraph: use a mutação agentApplicationCreateMobile:

mutation {
  agentApplicationCreateMobile(
    accountId: YOUR_ACCOUNT_ID
    name: "My New Mobile App"
  ) {
    accountId
    applicationToken
    guid
    name
  }
}

Dica

A resposta inclui um applicationToken que é necessário para configurar o agente móvel no aplicativo. O guid é o GUID da entidade para consultas subsequentes do NerdGraph.

Para obter mais informações, consulte Tutorial de Configuração Mobile.

Aplicativo Browser

Listar aplicativo de browser

NerdGraph:

{
  actor {
    entitySearch(
      query: "domain = 'BROWSER' AND type = 'APPLICATION' AND accountId = YOUR_ACCOUNT_ID"
    ) {
      results {
        entities {
          guid
          name
          reporting
          ... on BrowserApplicationEntityOutline {
            applicationId
            browserSummary {
              ajaxRequestThroughput
              ajaxResponseTimeAverage
              jsErrorRate
              pageLoadThroughput
              pageLoadTimeAverage
              spaResponseTimeAverage
            }
          }
        }
        nextCursor
      }
    }
  }
}

Dica

Para encontrar o GUID da entidade de um aplicativo de navegador a partir de um ID do aplicativo numérico:

{
  actor {
    entitySearch(query: "domainId = 'BROWSER_APP_ID' AND domain = 'BROWSER'") {
      results {
        entities {
          guid
          name
        }
      }
    }
  }
}

Criar aplicativo de browser autônomo

API REST v2: POST /v2/browser_applications.json (método de instalação de copiar/colar)

NerdGraph: use a mutação agentApplicationCreateBrowser:

mutation {
  agentApplicationCreateBrowser(
    accountId: YOUR_ACCOUNT_ID
    name: "My New Browser App"
    settings: {
      cookiesEnabled: true
      distributedTracingEnabled: true
      loaderType: SPA
    }
  ) {
    guid
    name
    settings {
      cookiesEnabled
      distributedTracingEnabled
      loaderType
    }
  }
}

Dica

O parâmetro settings é opcional. Se omitido, os padrões serão usados. As opções de loaderType são SPA (padrão), PRO e LITE.

Ativar o monitoramento de Browser em um aplicativo APM

API REST v2: a ativação do monitoramento de Browser em um aplicativo APM existente era feita por meio das configurações do aplicativo.

NerdGraph: usar a mutação agentApplicationEnableApmBrowser com o GUID da entidade do aplicativo APM:

mutation {
  agentApplicationEnableApmBrowser(
    guid: "YOUR_APM_ENTITY_GUID"
    settings: {
      cookiesEnabled: true
      distributedTracingEnabled: true
      loaderType: SPA
    }
  ) {
    name
    settings {
      cookiesEnabled
      distributedTracingEnabled
      loaderType
    }
  }
}

Dica

Isso permite a autoinjeção do agente do browser em páginas servidas pelo aplicativo APM. O parâmetro settings é opcional. O guid deve ser o GUID da entidade do aplicativo APM, não um GUID de entidade de browser. Isso geralmente não é necessário para novos aplicativos APM se a configuração local for usada para controlar o monitoramento de usuário real.

Para obter mais informações, consulte Tutorial de Configuração do Browser.

alerta

Listar canais

API REST v2: GET /v2/alerts_channels.json

NerdGraph: não há consulta direta para canais no NerdGraph. Recomenda-se migrar para o uso de fluxos de trabalho de notificação.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiWorkflows {
        workflows {
          entities {
            guid
            name
            workflowEnabled
            destinationConfigurations {
              channelId
              name
              type
            }
            destinationsEnabled
            lastRun
          }
        }
      }
    }
  }
}

Listar eventos

API REST v2: GET /v2/alerts_events.json

NerdGraph:

Listar incidente

API REST v2: GET /v2/alerts_incidents.json

NerdGraph:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiIssues {
        issues {
          issues {
            account {
              id
            }
            activatedAt
            closedAt
            conditionFamilyId
            conditionName
            description
            deepLinkUrl
            entityGuids
            entityNames
          }
        }
      }
    }
  }
}

Listar violações

API REST v2: GET /v2/alerts_violations.json

NerdGraph: Use a consulta de incidentes aiIssues:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiIssues {
        incidents(
          filter: {}
          timeWindow: { startTime: 1779905700000, endTime: 1779905800000 }
        ) {
          incidents {
            account {
              id
              name
            }
            closedAt
            createdAt
            description
            entityGuids
            entityNames
            entityTypes
            incidentId
            issueId
            priority
            state
            timestamp
            title
            updatedAt
          }
        }
      }
    }
  }
}

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

Importante

Dica

Antes de você começar.css-21sua1{background:none;border:none;width:0;padding:0;}

Obter uma chave de API do usuário

Endpoints do NerdGraph

Explorar interativamente

GUIDs da Entidade

Autenticação

Principais Diferenças

Aplicativos

Listar aplicativos

Dica

Mostrar aplicativo

Dica

Atualizar configurações do aplicativo

Dica

Excluir aplicativo

Dados de métrica do aplicativo

Listar nomes métricos

Dica

Obter dados métricos

Dica

Mapeamento do valor da métrica da API REST para a função NRQL

Hosts e instâncias do aplicativo

Listar hosts do aplicativo

Dica

Dados de métrica de host/instância do aplicativo

Implantação

Listar implantações

Criar implantação

Dica

Excluir implantação

Transação principal

Listar transações principais

Dica

Mostrar transação principal

Aplicativo móvel

Listar aplicativos mobile

Mostrar aplicativo mobile

Dica

Dados de métrica de aplicativo móvel

Criar aplicativo mobile

Dica

Aplicativo Browser

Listar aplicativo de browser

Dica

Criar aplicativo de browser autônomo

Dica

Ativar o monitoramento de Browser em um aplicativo APM

Dica

alerta

Listar canais

Listar eventos

Listar incidente

Listar violações

Antes de você começar