Migrar de la API REST v2 a NerdGraph

Esta guía le ayuda a migrar de la API de REST v2 de New Relic a la API GraphQL de NerdGraph. NerdGraph es la API recomendada de New Relic, que ofrece un único extremo unificado, una obtención de datos precisa y un tipado fuerte.

Importante

The New Relic REST API v2 (including Alerts endpoints) and the Deployments v0 API will reach end of life on July 31, 2027. After this date, these endpoints will no longer be available. Migrate your integrations to NerdGraph before that date.

Sugerencia

Las consultas de esta guía son un punto de partida — no reemplazos directos para los extremos de REST v2. Con cualquier consulta base, puede omitir los campos que no necesite o agregar campos que tal vez no hayan estado disponibles en la llamada REST original. En algunos casos, como en las colecciones de objetos "outline" frente a los campos de detalles, la coincidencia exacta de campos no es posible directamente.

Antes de que empieces

Obtener una clave de API de usuario

Puede reutilizar la clave de API de usuario que ya usa para realizar llamadas REST, pero tenga en cuenta que la API REST v2 hizo suposiciones basadas en la cuenta utilizada para crear la clave de API de usuario. NerdGraph no hace suposiciones similares.

Extremos de NerdGraph

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

Explorar de forma interactiva

Utilice el explorador de la API NerdGraph para crear y probar consultas con documentación en línea y autocompletado.

GUID de entidad

NerdGraph normalmente usa GUID de entidad (identificadores únicos globales) en lugar de ID de la aplicación numéricos. Puede buscar un GUID de entidad a partir de un ID de la aplicación de la API REST mediante una consulta de búsqueda de entidad (consulte Aplicaciones). El seguimiento de cambios aún se puede realizar con solo un appId.

Autenticación

API de 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 obtener más información, consulte Introducción a NerdGraph.

Diferencias clave

Característica	API REST v2	NerdGraph (GraphQL)
Protocolo	Múltiples extremos REST	Extremo único de GraphQL
Autenticación	Clave de API de usuario (encabezado `Api-Key` o `X-Api-Key` )	Clave de API de usuario (encabezado `Api-Key` ), identidades del sistema
Obtención de datos	Formas de respuesta corregidas	Forma de la respuesta determinada por la consulta dada
Identificador	ID numéricos (por ejemplo, ID de la aplicación)	Enteros para cuentas, GUID de entidad para aplicaciones, etc.
Listas frente a detalles	Objetos completos devueltos en extremos de lista	Muchos campos de colección solo incluyen un objeto "Outline". Es posible que deba consultar un solo elemento para obtener más detalles.
Paginación	Basado en páginas ( `?page=N` )	Paginación basada en cursor
Datos métricos	Extremos de métrica dedicados	Consultas NRQL a través de `actor.nrql` o `actor.account.nrql`
Límites de tasa	Límites por clave	Límites de concurrencia y rendimiento

Aplicaciones

Enumerar aplicaciones

API de REST v2: GET /v2/applications.json

NerdGraph: Use entitySearch para encontrar aplicaciones de APM. Agregue accountId = YOUR_ACCOUNT_ID para limitar los resultados a una cuenta específica. No es necesario que proporcione un accountId, y puede buscar una aplicación específica agregando 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 nombre (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
        }
      }
    }
  }
}

Sugerencia

La API REST GET /v2/applications.json puede devolver aplicaciones que ya no reportan datos o que han sido eliminadas. NerdGraph entitySearch solo devuelve entidades que están indexadas en la plataforma de entidades. Si ve menos resultados de NerdGraph, la causa probable son las aplicaciones que no reportan o que llevan mucho tiempo inactivas.

Mostrar aplicación

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

NerdGraph: Obtener por GUID de entidad:

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

Sugerencia

Para encontrar el GUID de entidad a partir de un ID de la aplicación de la API REST:

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

Actualizar la configuración de la aplicación

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

Sugerencia

Hay muchas más configuraciones disponibles. Consulte los documentos en línea en el explorador de la API de NerdGraph para obtener una lista completa.

Eliminar aplicación

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

NerdGraph:

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

Para obtener más información, consulte el tutorial de entidades de NerdGraph y el tutorial de configuración de APM.

Datos métricos de la aplicación

Listar nombres métricos

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

NerdGraph: Use una consulta NRQL para enumerar los nombres de métricas disponibles:

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

O filtrar por nombre de la aplicación:

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

Sugerencia

La API REST devuelve todos los nombres de métricas conocidos históricamente independientemente del período de tiempo, junto con los tipos de valores disponibles para cada métrica (por ejemplo, average_response_time, call_count, calls_per_minute). La consulta NRQL solo devuelve métricas que han reportado datos dentro del período SINCE — amplíelo (por ejemplo, SINCE 1 WEEK AGO) para descubrir más nombres de métricas. NerdGraph no tiene un equivalente para enumerar los tipos de valores por métrica. En su lugar, use la tabla de mapeo de resumen a continuación (o siga el enlace a más mapeos) para traducir los nombres de valores de la API REST a funciones NRQL — todas las métricas de intervalo de tiempo admiten el mismo conjunto de funciones de agregación.

Obtener datos métricos

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

NerdGraph: Use consultas NRQL con las funciones de agregación adecuadas. Agregue TIMESERIES para obtener puntos de datos por intervalo (equivalente a la matriz de intervalo de tiempo de la 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
    }
  }
}

Sugerencia

Sin TIMESERIES, NRQL devuelve un único valor agregado para todo el rango de tiempo. La API REST devuelve intervalos de tiempo por minuto de forma predeterminada. Agregue TIMESERIES 1 minute para que coincida con la granularidad predeterminada de la API REST.

Mapeo de valores de métrica de la API REST a funciones de NRQL

Valor de la API REST	Función de 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 obtener más información, consulte Introducción a la API de métrica, Guía de consulta de métrica y Migrar consultas de intervalos de tiempo de métrica a NRQL.

Hosts e instancias de la aplicación

Enumerar hosts de la aplicación

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

NerdGraph: Utilice NRQL para consultar datos a nivel de host:

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

Sugerencia

El enfoque FROM Transaction solo devuelve los hosts que han procesado transacciones dentro de la ventana SINCE.

Datos de métricas de host/instancia de la aplicación

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

NerdGraph: Filtre las consultas NRQL por host o instancia de 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
    }
  }
}

Despliegue

Enumerar despliegues

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

NerdGraph: Consulte los despliegues a través de 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
    }
  }
}

Crear despliegue

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

NerdGraph: Use la mutación 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
    }
  }
}

Sugerencia

Al igual que algunas otras operaciones de NerdGraph, changeTrackingCreateEvent acepta un entitySearch, lo que lo convierte en la ruta de migración más fácil desde la API REST. Puede buscar por name así como por entityGuid si lo tiene. Consulte Rastrear cambios usando NerdGraph para ver todos los campos disponibles.

Eliminar despliegue

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

NerdGraph: No hay una mutación de eliminación directa para los despliegues en NerdGraph. Los registros de despliegue son eventos de seguimiento de cambios inmutables.

Para obtener más información, consulte Rastrear cambios usando NerdGraph.

Clave de transacción

Enumerar transacciones clave

API de REST v2: GET /v2/key_transactions.json

NerdGraph: Use la búsqueda de entidades con el tipo KEY_TRANSACTION. Agregue accountId para limitar a una cuenta específica:

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

Sugerencia

El tipo KeyTransactionEntityOutline no incluye métricas de resumen como el tiempo de respuesta o el rendimiento directamente. Para obtener datos de rendimiento para una transacción clave, use la consulta de entidad completa a continuación o ejecute una consulta NRQL con el nombre de la métrica de la transacción clave.

Mostrar transacción clave

API de 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 obtener métricas de rendimiento equivalentes (por ejemplo, rendimiento), use una consulta NRQL con el nombre de la métrica de la transacción clave:

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

aplicación móvil

Enumerar aplicaciones móviles

API de 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 aplicación móvil

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

Sugerencia

Para encontrar el GUID de entidad a partir de un ID de la aplicación móvil de la API REST:

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

Datos de métricas de la aplicación móvil

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

NerdGraph: Usar NRQL para consultar datos de métricas móviles:

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

Crear aplicación móvil

API de REST v2: POST /v2/mobile_applications.json

NerdGraph: Utilice la mutación agentApplicationCreateMobile:

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

Sugerencia

La respuesta incluye un applicationToken que es necesario para configurar el agente móvil en su aplicación. El guid es el GUID de entidad para las consultas posteriores de NerdGraph.

Para obtener más información, consulte Tutorial de configuración móvil.

Aplicación Browser

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

Sugerencia

Para encontrar un GUID de entidad de aplicación de navegador a partir de un ID de la aplicación numérico:

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

Crear aplicación de browser independiente

API REST v2: POST /v2/browser_applications.json (método de instalación de copiar y pegar)

NerdGraph: Utilice la mutación 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
    }
  }
}

Sugerencia

El parámetro settings es opcional. Si se omite, se usarán los valores predeterminados. Las opciones de loaderType son SPA (predeterminado), PRO y LITE.

Habilitar el monitoreo de browser en una aplicación de APM

API de REST v2: La habilitación del monitoreo de browser en una aplicación de APM existente se realizaba a través de la configuración de la aplicación.

NerdGraph: Utilice la mutación agentApplicationEnableApmBrowser con el GUID de entidad de la aplicación de APM:

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

Sugerencia

Esto habilita la inyección automática del agente del browser en las páginas servidas por la aplicación APM. El parámetro settings es opcional. El guid debe ser el GUID de la entidad de la aplicación APM, no un GUID de la entidad del browser. A menudo, esto no es necesario para las nuevas aplicaciones APM si utiliza su configuración local para controlar el monitoreo de usuarios reales.

Para obtener más información, consulte el tutorial de configuración de Browser.

Alerta

Enumerar canales

API de REST v2: GET /v2/alerts_channels.json

NerdGraph: No hay una consulta directa para canales en NerdGraph. Debe migrar al uso de flujos de trabajo de notificación.

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

Enumerar eventos

API de REST v2: GET /v2/alerts_events.json

NerdGraph:

Lista de incidentes

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

Enumerar infracciones

API de REST v2: GET /v2/alerts_violations.json

NerdGraph: Use la 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
          }
        }
      }
    }
  }
}

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

Importante

Sugerencia

Antes de que empieces.css-21sua1{background:none;border:none;width:0;padding:0;}

Obtener una clave de API de usuario

Extremos de NerdGraph

Explorar de forma interactiva

GUID de entidad

Autenticación

Diferencias clave

Aplicaciones

Enumerar aplicaciones

Sugerencia

Mostrar aplicación

Sugerencia

Actualizar la configuración de la aplicación

Sugerencia

Eliminar aplicación

Datos métricos de la aplicación

Listar nombres métricos

Sugerencia

Obtener datos métricos

Sugerencia

Mapeo de valores de métrica de la API REST a funciones de NRQL

Hosts e instancias de la aplicación

Enumerar hosts de la aplicación

Sugerencia

Datos de métricas de host/instancia de la aplicación

Despliegue

Enumerar despliegues

Crear despliegue

Sugerencia

Eliminar despliegue

Clave de transacción

Enumerar transacciones clave

Sugerencia

Mostrar transacción clave

aplicación móvil

Enumerar aplicaciones móviles

Mostrar aplicación móvil

Sugerencia

Datos de métricas de la aplicación móvil

Crear aplicación móvil

Sugerencia

Aplicación Browser

Enumerar aplicaciones de browser

Sugerencia

Crear aplicación de browser independiente

Sugerencia

Habilitar el monitoreo de browser en una aplicación de APM

Sugerencia

Alerta

Enumerar canales

Enumerar eventos

Lista de incidentes

Enumerar infracciones

Antes de que empieces