Migrer de l'API REST v2 vers NerdGraph

Ce guide vous aide à migrer de l'API REST v2 de New Relic vers l'API GraphQL NerdGraph. NerdGraph est l’API recommandée par New Relic, offrant un point de terminaison unifié unique, une récupération précise des données et un typage fort.

Important

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.

Conseil

Les requêtes de ce guide sont un point de départ — et non des substituts directs pour les points de terminaison REST v2. Avec n'importe quelle requête de base, vous pouvez omettre les champs dont vous n'avez pas besoin ou ajouter des champs qui n'étaient peut-être pas disponibles dans l'appel REST d'origine. Dans certains cas, comme les collections d'objets « outline » par rapport aux champs de détail, une correspondance exacte des champs n'est pas possible directement.

Avant de commencer

Obtenir une clé API utilisateur

Vous pouvez réutiliser la clé API utilisateur que vous utilisez déjà pour effectuer des appels REST, mais notez que l’API REST v2 faisait des suppositions basées sur le compte utilisé pour créer la clé API utilisateur. NerdGraph ne fait pas de telles suppositions.

Points de terminaison NerdGraph

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

Explorer interactivement

Utilisez l’ explorateur de l’API NerdGraph pour créer et tester des requêtes avec une documentation en ligne et l’autocomplétion.

GUID d’entité

NerdGraph utilise généralement des GUID d’entité (identifiants uniques globaux) au lieu d’identifiants d’application numériques. Vous pouvez rechercher un GUID d’entité à partir d’un identifiant d’application de l’API REST à l’aide d’une requête de recherche d’entité (voir Applications). Le suivi des changements peut toujours être effectué avec seulement un appId.

Authentification

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

Pour plus d’informations, consultez Introduction à NerdGraph.

Principales différences

Fonctionnalité	API REST v2	NerdGraph (GraphQL)
Protocole	Plusieurs points de terminaison REST	Point de terminaison GraphQL unique
Authentification	Clé API utilisateur (en-tête `Api-Key` ou `X-Api-Key` )	Clé API utilisateur (en-tête `Api-Key` ), identités système
Récupération de données	Structures de réponse fixes	Forme de réponse déterminée par la requête donnée
identifiant	Identifiants numériques (par ex., identifiant d’application)	Entiers pour les comptes, GUID d'entité pour les applications, etc.
Listes vs détails	Objets complets renvoyés dans les points de terminaison de liste	De nombreux champs de collection n'incluent qu'un objet "Outline". Vous devrez peut-être effectuer une requête sur un seul élément pour obtenir plus de détails.
Pagination	Basé sur la page ( `?page=N` )	Pagination basée sur un curseur
données métriques	Points de terminaison de métrique dédiés	Requêtes NRQL via `actor.nrql` ou `actor.account.nrql`
Limites des tarifs	Limites par clé	Limites de simultanéité et de débit

Applications

Lister les applications

API REST v2 : GET /v2/applications.json

NerdGraph : utilisez entitySearch pour trouver des applications APM. Ajoutez accountId = YOUR_ACCOUNT_ID pour limiter les résultats à un compte spécifique. Vous n'êtes pas obligé de fournir un accountId, et vous pouvez rechercher une application spécifique en ajoutant 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
      }
    }
  }
}

Pour filtrer par nom (équivalent à filter[name]) :

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

Conseil

L'API REST GET /v2/applications.json peut retourner des applications qui ne transmettent plus de données ou qui ont été supprimées. NerdGraph entitySearch retourne uniquement les entités qui sont indexées dans la plateforme d'entités. Si vous obtenez moins de résultats de NerdGraph, les applications ne transmettant pas de données ou inactives depuis longtemps en sont probablement la cause.

Afficher l'application

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

NerdGraph : récupérer par GUID d'entité :

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

Conseil

Pour trouver le GUID de l’entité à partir d’un identifiant d’application de l’API REST :

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

Mettre à jour les paramètres de l'application

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

Conseil

De nombreux autres paramètres sont disponibles. Consultez la documentation intégrée dans le NerdGraph API Explorer pour obtenir une liste complète.

Supprimer l'application

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

NerdGraph :

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

Pour plus d'informations, consultez le didacticiel sur les entités NerdGraph et le didacticiel sur les paramètres APM.

Données de métrique d'application

Lister les noms métriques

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

NerdGraph : utilisez une requête NRQL pour lister les noms de métriques 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
    }
  }
}

Ou filtrer par nom d'application :

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

Conseil

L’API REST renvoie tous les noms de métriques historiquement connus indépendamment de la fenêtre de temps, ainsi que les types de valeurs disponibles pour chaque métrique (par exemple, average_response_time, call_count, calls_per_minute). La requête NRQL renvoie uniquement les métriques qui ont signalé des données dans la fenêtre SINCE — étendez-la (par exemple, SINCE 1 WEEK AGO) pour découvrir plus de noms de métriques. NerdGraph n’a pas d’équivalent pour lister les types de valeurs par métrique. Utilisez plutôt le tableau de modélisation récapitulatif ci-dessous (ou suivez le lien vers plus de modélisations) pour traduire les noms de valeurs de l’API REST en fonctions NRQL — toutes les métriques de tranches de temps prennent en charge le même ensemble de fonctions d’agrégation.

Obtenir des données de métrique

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

NerdGraph : utilisez des requêtes NRQL avec les fonctions d'agrégation appropriées. Ajoutez TIMESERIES pour obtenir des points de données par intervalle (équivalent à l'éventail d'intervalles de temps de l'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
    }
  }
}

Conseil

Sans TIMESERIES, NRQL renvoie une seule valeur agrégée pour l’ensemble de la plage de temps. L’API REST renvoie par défaut des intervalles de temps par minute. Ajoutez TIMESERIES 1 minute pour correspondre à la granularité par défaut de l’API REST.

Modélisation de la valeur de métrique de l'API REST vers la fonction NRQL

Valeur de l’API REST	Fonction 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`

Pour plus d'informations, consultez Introduction à l'API de métrique, le Guide de requête de métrique et Migrer les requêtes d'intervalle de temps métrique vers NRQL.

Hôtes et instances d'application

Lister les hôtes d’application

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

NerdGraph : Utilisez NRQL pour interroger les données au niveau de l’hôte :

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

Conseil

L’approche FROM Transaction ne renvoie que les hôtes qui ont traité des transactions dans la fenêtre SINCE.

Données de métrique d'hôte/instance d'application

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

NerdGraph : filtrez les requêtes NRQL par hôte ou instance d'agent :

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

déploierons

Lister les déploiements

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

NerdGraph : requête de déploiements 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
    }
  }
}

Créer un déploiement

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

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

Conseil

Comme certaines autres opérations NerdGraph, changeTrackingCreateEvent accepte un entitySearch, ce qui en fait le chemin de migration le plus simple depuis l'API REST. Vous pouvez rechercher par name ainsi que par entityGuid si vous l’avez. Consultez Suivre les modifications à l’aide de NerdGraph pour tous les champs disponibles.

Supprimer le déploiement

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

NerdGraph : il n'y a pas de mutation de suppression directe pour les déploiements dans NerdGraph. Les enregistrements de déploiement sont des événements de suivi des changements immuables.

Pour plus d’informations, consultez Suivre les modifications à l’aide de NerdGraph.

clé de transaction

Lister les transactions clés

API REST v2 : GET /v2/key_transactions.json

NerdGraph : utilisez la recherche d'entité avec le type KEY_TRANSACTION. Ajouter accountId pour définir la portée sur un compte spécifique :

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

Conseil

Le type KeyTransactionEntityOutline n’inclut pas directement de métriques récapitulatives comme le temps de réponse ou le débit. Pour obtenir des données de performance pour une transaction clé, utilisez la requête d’entité complète ci-dessous ou exécutez une requête NRQL sur le nom de la métrique de la transaction clé.

Afficher la transaction clé

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

Pour obtenir des métriques de performances équivalentes (par exemple, le débit), utilisez une requête NRQL avec le nom de métrique de la transaction clé :

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

Applications mobiles

Lister les applications mobiles

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

Afficher l'application 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
        }
      }
    }
  }
}

Conseil

Pour trouver le GUID d’entité à partir d’un identifiant d’application mobile de l’API REST :

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

Données de métrique d'application mobile

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

NerdGraph : utilisez NRQL pour interroger les données de métriques mobiles :

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

Créer une application mobile

API REST v2 : POST /v2/mobile_applications.json

NerdGraph : Utilisez la mutation agentApplicationCreateMobile :

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

Conseil

La réponse inclut un applicationToken qui est nécessaire pour configurer l’agent mobile dans votre application. Le guid est le GUID d’entité pour les requêtes NerdGraph ultérieures.

Pour plus d'informations, consultez le tutoriel de configuration mobile.

Applications Browser

Liste des applications de navigateur

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

Conseil

Pour trouver un GUID d’entité d’application de navigateur à partir d’un identifiant d’application numérique :

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

Créer une application de navigateur autonome

API REST v2 : POST /v2/browser_applications.json (méthode d’installation par copier/coller)

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

Conseil

Le paramètre settings est facultatif. Si omis, les valeurs par défaut seront utilisées. Les options loaderType sont SPA (par défaut), PRO et LITE.

Activer le monitoring de navigateurs sur une application APM

API REST v2 : L’activation du monitoring de navigateurs sur une application APM existante se faisait via les paramètres de l’application.

NerdGraph : utilisez la mutation agentApplicationEnableApmBrowser avec le GUID de l'entité de l'application APM :

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

Conseil

Cela permet l’auto-injection de l’agent de navigateur dans les pages servies par l’application APM. Le paramètre settings est facultatif. Le guid doit être le GUID de l’entité de l’application APM, et non le GUID d’une entité de navigateur. Cela n’est souvent pas nécessaire pour les nouvelles applications APM si vous utilisez votre configuration locale pour contrôler le monitoring des utilisateurs réels.

Pour plus d'informations, consultez le tutoriel de configuration de Browser.

Alertes

Liste des canaux

API REST v2 : GET /v2/alerts_channels.json

NerdGraph : Il n'y a pas de requête directe pour les canaux dans NerdGraph. Vous devriez migrer vers l'utilisation des workflows de notification.

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

Lister les événements

API REST v2 : GET /v2/alerts_events.json

NerdGraph :

Liste des incidents

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

Lister les violations

API REST v2 : GET /v2/alerts_violations.json

NerdGraph : utilisez la requête d’incidents 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
          }
        }
      }
    }
  }
}

Cette traduction automatique est fournie pour votre commodité.

Important

Conseil

Avant de commencer.css-21sua1{background:none;border:none;width:0;padding:0;}

Obtenir une clé API utilisateur

Points de terminaison NerdGraph

Explorer interactivement

GUID d’entité

Authentification

Principales différences

Applications

Lister les applications

Conseil

Afficher l'application

Conseil

Mettre à jour les paramètres de l'application

Conseil

Supprimer l'application

Données de métrique d'application

Lister les noms métriques

Conseil

Obtenir des données de métrique

Conseil

Modélisation de la valeur de métrique de l'API REST vers la fonction NRQL

Hôtes et instances d'application

Lister les hôtes d’application

Conseil

Données de métrique d'hôte/instance d'application

déploierons

Lister les déploiements

Créer un déploiement

Conseil

Supprimer le déploiement

clé de transaction

Lister les transactions clés

Conseil

Afficher la transaction clé

Applications mobiles

Lister les applications mobiles

Afficher l'application mobile

Conseil

Données de métrique d'application mobile

Créer une application mobile

Conseil

Applications Browser

Liste des applications de navigateur

Conseil

Créer une application de navigateur autonome

Conseil

Activer le monitoring de navigateurs sur une application APM

Conseil

Alertes

Liste des canaux

Lister les événements

Liste des incidents

Lister les violations

Avant de commencer