Tutoriel NerdGraph : Canaux d'alertes

En plus de gérer votre canal d'alerte de notification dans l'UI, vous pouvez utiliser notre API NerdGraph.

Important

Ce document fait référence à l'utilisation API Nerdgraph pour la nouvelle plateforme notification utilisant des destinations et des messages notification . les messages de notification sont également appelés canaux, qui sont différents des legacy canaux de notification.

Conseil

Pour obtenir de l’aide pour démarrer avec NerdGraph, consultez Introduction à NerdGraph.

Lister et filtrer les chaînes

La requête channels vous permet de parcourir tous vos canaux par compte. Il permet également certaines fonctionnalités de filtrage.

Voici un exemple :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels {
          entities {
            id
            name
          }
          error {
            details
          }
        }
      }
    }
  }
}

Afin de parcourir vos chaînes, vous devez demander le champ nextCursor lors de votre requête initiale.

Avec la pagination du curseur, vous continuez à effectuer une requête via l'ensemble de résultats jusqu'à ce que le nextCursor renvoyé par la réponse revienne vide. Cela signifie que vous avez atteint la fin de vos résultats.

Voici un exemple :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(cursor: "") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}

Le code ci-dessus renvoie un ensemble de résultats comme celui-ci :

{
  "data": {
    "actor": {
      "account": {
        "aiNotifications": {
          "channels": {
            "nextCursor": "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=",
            "entities": [
              {
                "id": "01c0cbe7-3d70-47c1-99e0-adf906eed6c2",
                "name": "Channel Name"
              },
              {
                "id": "05db0207-c137-4985-8cb5-f21e7e57b8cc",
                "name": "Another Channel Name"
              }
              // ... more channels here in reality
            ],
            "totalCount": 807
          }
        }
      }
    }
  }
}

Ainsi, dans votre requête suivante, fournissez le curseur comme ceci, jusqu'à ce que le curseur soit vide :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(cursor: "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}

L'API permet d'interroger les canaux par nom. Le filtre name renvoie des correspondances exactes et des correspondances partielles. Il n'est pas sensible à la casse. Cela renverra uniquement les informations pour les chaînes qui correspondent au nom fourni.

Dans cet exemple, nous souhaitons trouver les chaînes avec "DevOps" dans le nom :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { name: "DevOps" }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

L'API vous permet d'effectuer une requête par ID de canal :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { id: YOUR_CHANNEL_ID }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

L'API vous permet d'interroger les canaux par ID de destination :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { destinationId: YOUR_DESTINATION_ID }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

L'API vous permet d'effectuer des requêtes par type de canal. La requête suivante renverra tous les canaux de messagerie sur le compte choisi :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { type: EMAIL }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

Créer une chaîne

Afin de créer un canal, des entrées différentes doivent être fournies pour chaque type de canal. Chaque canal est connecté à une destination. Pour plus d'informations sur les destinations, consultez le didacticiel NerdGraph sur les destinations.

La bonne pratique consiste à utiliser le point de terminaison channelSchema pour voir quels champs doivent être envoyés sous properties comme ceci :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: CHANNEL_TYPE
          destinationId: YOUR_DESTINATION_ID
          product: YOUR_PRODUCT
          constraints: []
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}

Jira est un système de tickets configurable, et il n'existe donc aucun moyen statique de créer ce canal.

Il existe deux champs statiques : project et issuetype.

Récupérez les suggestions project et utilisez l'une des valeurs comme contrainte pour issuetype, comme indiqué ici :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSuggestions(
          channelType: JIRA_CLASSIC
          destinationId: YOUR_DESTINATION_ID
          key: FIELD_NAME
          constraints: [{ key: "project", value: YOUR_PROJECT_VALUE }]
        ) {
          entities {
            value
          }
          error
        }
      }
    }
  }
}

Les valeurs choisies seront utilisées comme contraintes pour récupérer le schéma :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: JIRA_CLASSIC
          destinationId: YOUR_DESTINATION_ID
          product: YOUR_PRODUCT
          constraints: [
            { key: "project", value: YOUR_PROJECT_VALUE }
            { key: "issuetype", value: YOUR_ISSUE_TYPE_VALUE }
          ]
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}

Après avoir récupéré chaque champ et choisi une valeur parmi les suggestions ou sous forme de texte libre, vous pouvez créer un canal :

mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: JIRA,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: YOUR_FIELD_NAME,
        value: YOUR_FIELD_NAME,
      },
      // ... And so forth with the rest of the fields
    ]
  }) {
    channel {
      id
      name
    }
  }
}

ServiceNow est un système de tickets configurable, il n'existe donc aucun moyen statique de créer ce canal.

Le schéma doit être récupéré comme indiqué ci-dessus, puis chaque champ doit être rempli avec du texte libre ou en utilisant des suggestions :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: SERVICE_NOW
          destinationId: YOUR_DESTINATION_ID
          product: YOUR_PRODUCT
          constraints: []
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}

Après avoir récupéré chaque champ et choisi une valeur parmi les suggestions ou sous forme de texte libre, vous pouvez créer un canal :

mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: SERVICE_NOW,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: YOUR_FIELD_NAME,
        value: YOUR_FIELD_NAME,
      },
      // ... And so forth with the rest of the fields
    ]
  }) {
    channel {
      id
      name
    }
  }
}

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: SLACK
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [{ key: "channelId", value: YOUR_SLACK_CHANNEL_ID }]
    }
  ) {
    channel {
      id
      name
    }
  }
}

Note

L'intégration de Microsoft Teams est désormais disponible aux États-Unis et dans l'Union européenne.

Prérequis

Avant de configurer New Relic pour envoyer des notifications à Microsoft Teams, vous devez :

Vous disposez déjà d'un canal Microsoft Teams dans lequel vous souhaitez recevoir des notifications.

Créez une destination Microsoft Teams dans New Relic et obtenez le destinationId.

Étape 1 : Récupérer les identifiants d’équipe disponibles

Conseil

Si vous connaissez déjà votre ID d'équipe et votre ID de canal, vous pouvez ignorer les étapes 1 et 2 et passer directement à l'étape 3 pour configurer le canal de notification.

Cette requête permet de découvrir quelles équipes Microsoft Teams sont accessibles via votre destination. Vous fournissez destinationId et spécifiez que vous souhaitez des identifiants d'équipe (via key: "teamId"), et l'API renvoie une liste des équipes disponibles avec leurs noms et identifiants :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        suggestions(
          destinationId: YOUR_DESTINATION_ID
          key: "teamId"
          channelType: MICROSOFT_TEAMS
          constraints: []
        ) {
          entities {
            displayValue
            value
          }
          errors {
            description
            details
            type
          }
        }
      }
    }
  }
}

La réponse contiendra une liste d'équipes avec leurs noms d'affichage et leurs identifiants d'équipe uniques :

{
  "data": {
    "actor": {
      "account": {
        "aiNotifications": {
          "suggestions": {
            "entities": [
              {
                "displayValue": "Engineering Team",
                "value": "389e7f6c-xxxx-47f0-aa77-xxxxxxxxxxxx"
              },
              {
                "displayValue": "DevOps Team",
                "value": "834dc358-xxxx-4445-9938-xxxxxxxxxxxx"
              }
            ],
            "errors": []
          }
        }
      }
    }
  }
}

Conseil

Si vous ne voyez pas l'équipe que vous recherchez dans les résultats, vous pouvez utiliser le paramètre filter pour la rechercher par son nom :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        suggestions(
          destinationId: YOUR_DESTINATION_ID
          key: "teamId"
          channelType: MICROSOFT_TEAMS
          constraints: []
          filter: { type: CONTAINS, value: "Engineering" }
        ) {
          entities {
            displayValue
            value
          }
        }
      }
    }
  }
}

Étape 2 : Récupérer les identifiants de canal disponibles pour une équipe

Une fois que vous avez obtenu un ID d'équipe à l'étape 1, cette requête permet de découvrir quels canaux existent au sein de cette équipe spécifique. Vous fournissez les destinationId et teamId (en tant que contrainte), et l'API renvoie une liste des canaux disponibles avec leurs noms et identifiants :

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        suggestions(
          destinationId: YOUR_DESTINATION_ID
          key: "channelId"
          channelType: MICROSOFT_TEAMS
          constraints: [{ key: "teamId", value: "YOUR_TEAM_ID" }]
        ) {
          entities {
            displayValue
            value
          }
          errors {
            description
            details
            type
          }
        }
      }
    }
  }
}

La réponse contiendra une liste des canaux de l'équipe spécifiée :

{
  "data": {
    "actor": {
      "account": {
        "aiNotifications": {
          "suggestions": {
            "entities": [
              {
                "displayValue": "General",
                "value": "19:xxxxxxxxxxxxxxxxxxxxxxxx@thread.tacv2"
              },
              {
                "displayValue": "Alerts",
                "value": "19:yyyyyyyyyyyyyyyyyyyyyyyy@thread.tacv2"
              }
            ],
            "errors": []
          }
        }
      }
    }
  }
}

Conseil

Tout comme pour les ID d'équipe, vous pouvez filtrer les chaînes par nom en utilisant le paramètre filter pour effectuer une recherche au sein de l'équipe spécifiée.

Étape 3 : Configurer le canal de notification New Relic

Après avoir obtenu l'ID d'équipe et l'ID de canal, configurez le canal de notification New Relic pour envoyer des alertes à votre canal Microsoft Teams.

Important

Cette mutation crée un objet de canal de notification New Relic qui se connecte à un canal Microsoft Teams existant. Le canal Teams doit déjà exister dans votre espace de travail Microsoft Teams. Cette API ne crée pas de nouvelles équipes ou de nouveaux canaux au sein de Microsoft Teams ; elle configure uniquement New Relic pour envoyer des notifications à vos canaux Teams existants.

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: MICROSOFT_TEAMS
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [
        { key: "teamId", value: YOUR_TEAM_ID }
        { key: "channelId", value: YOUR_CHANNEL_ID }
      ]
    }
  ) {
    channel {
      id
      name
    }
  }
}

Le paramètre product spécifie le produit New Relic générant la notification. Les valeurs valides incluent :

IINT - renseignement appliqué (incident Intelligence)
ALERTS
ERROR_TRACKING
APM - Monitoring des performances des applications
CHANGE_TRACKING
SECURITY
PD - Détection proactive
Autres valeurs : CSSP, DISCUSSIONS, NTFC, SHARING

La propriété payload est la charge utile qui sera envoyée dans la notification. Il utilise la syntaxe de Handlebars pour insérer dynamiquement des informations à partir de la requête.

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: WEBHOOK
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [{ key: "payload", value: "{\"key\":\"value\"}" }]
    }
  ) {
    channel {
      id
      name
    }
  }
}

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: EMAIL
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: []
    }
  ) {
    channel {
      id
      name
    }
  }
}

Le eventSource doit être l’URL complète d’une source d’événement existante. Le eventContent est la charge utile qui sera envoyée dans le corps de la notification, comme indiqué ici :

mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: EVENT_BRIDGE,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: "eventSource",
        value:  YOUR_AWS_EVENT_SOURCE
      },
      {
        key: "eventContent",
        value:  YOUR_EVENT_CONTENT/var>
      }
    ]
  }) {
    channel {
      id
      name
    }
  }
}

PagerDuty a deux types d'intégration, niveau de service et niveau de compte. Pour plus d'informations, consultez la documentation d'intégration de PagerDuty.

Niveau de service:

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: PAGERDUTY_SERVICE_INTEGRATION
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [{ key: "summary", value: YOUR_PAGE_SUMMARY }]
    }
  ) {
    channel {
      id
      name
    }
  }
}

Niveau du compte :

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: PAGERDUTY_ACCOUNT_INTEGRATION
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [
        { key: "summary", value: YOUR_PAGE_SUMMARY }
        { key: "email", value: EMAIL_OF_PD_USER }
        { key: "service", value: YOUR_PD_SERVICE_ID }
      ]
    }
  ) {
    channel {
      id
      name
    }
  }
}

Mettre à jour une chaîne

Lorsque vous mettez à jour un canal, notez que vous n'avez pas besoin de fournir tous les attributs du canal. Par exemple, si vous souhaitez uniquement mettre à jour le nom, c'est le seul attribut que vous devez mettre à jour, comme indiqué ici :

mutation {
  aiNotificationsUpdateChannel(
    accountId: YOUR_ACCOUNT_ID
    channelId: YOUR_CHANNEL_ID
    channel: { name: "Updated channel Name" }
  ) {
    channel {
      id
      name
    }
  }
}

Tester une chaîne

Vous pouvez tester les chaînes via l'API NerdGraph. Cela peut être fait avant ou après la création de la chaîne.

mutation {
  aiNotificationsTestChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: PAGERDUTY_SERVICE_INTEGRATION
      name: "Channel Name"
      properties: [{ key: "summary", value: YOUR_PAGE_SUMMARY }]
    }
  ) {
    error {
      details
    }
    details
    result
  }
}

mutation {
  aiNotificationsTestChannelById(
    accountId: YOUR_ACCOUNT_ID
    channelId: YOUR_CHANNEL_ID
  ) {
    error {
      details
    }
    details
    result
  }
}

Supprimer une chaîne

Vous pouvez supprimer des chaînes via l'API NerdGraph.

mutation {
  aiNotificationsDeleteChannel(
    accountId: YOUR_ACCOUNT_ID
    channelId: YOUR_CHANNEL_ID
  ) {
    ids
    error {
      details
    }
  }
}

Cette traduction automatique est fournie pour votre commodité.

Important

Conseil

Lister et filtrer les chaînes

Liste de toutes les chaînes d'un compte

Pagination des canaux avec pagination du curseur

Trouver toutes les chaînes par nom

Rechercher une chaîne par identifiant

Trouver toutes les chaînes par identifiant de destination

Trouver toutes les chaînes par type

Créer une chaîne

Atlassian Jira

ServiceNow (gestion des incidents)

Mou

Microsoft Teams

Note

Prérequis

Étape 1 : Récupérer les identifiants d’équipe disponibles

Conseil

Conseil

Étape 2 : Récupérer les identifiants de canal disponibles pour une équipe

Conseil

Étape 3 : Configurer le canal de notification New Relic

Important

Webhook

E-mail

AWS EventBridge

PagerDuty

Mettre à jour une chaîne

Tester une chaîne

Supprimer une chaîne

Cette traduction automatique est fournie pour votre commodité.

Tutoriel NerdGraph : Canaux d'alertes

Important

Conseil

Lister et filtrer les chaînes .css-21sua1{background:none;border:none;width:0;padding:0;}

Pagination des canaux avec pagination du curseur

Trouver toutes les chaînes par nom

Rechercher une chaîne par identifiant

Trouver toutes les chaînes par identifiant de destination

Trouver toutes les chaînes par type

Créer une chaîne

Atlassian Jira

ServiceNow (gestion des incidents)

Mou

Microsoft Teams

Webhook

E-mail

AWS EventBridge

PagerDuty

Mettre à jour une chaîne

Tester une chaîne

Supprimer une chaîne

Lister et filtrer les chaînes