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

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

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

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