Tutorial NerdGraph: canales de inteligencia aplicada

Además de administrar su canal de notificación de inteligencia aplicada en la UI, puede utilizar nuestra API NerdGraph.

Importante

Este documento hace referencia al uso de las API de Nerdgraph para la nueva plataforma de notificación utilizando destinos y mensajes de notificación. Los mensajes de notificación también se denominan canales, que son diferentes del canal de notificación legacy .

Sugerencia

Para obtener ayuda para comenzar con NerdGraph, consulte Introducción a NerdGraph.

Listar y filtrar canales

La consulta channels le permite paginar todos sus canales por cuenta. También permite algunas funciones de filtrado.

He aquí un ejemplo:

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

Para paginar a través de sus canales, debe solicitar el campo nextCursor en su consulta inicial.

Con la paginación del cursor, continúa realizando una solicitud a través del conjunto de resultados hasta que el nextCursor que se devuelve de la respuesta vuelve vacío. Esto significa que llegó al final de sus resultados.

He aquí un ejemplo:

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

El código anterior devuelve un conjunto de resultados como este:

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

Entonces, en su solicitud posterior, proporcione el cursor así, hasta que el cursor esté vacío:

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

La API permite consultar el canal por nombre. El filtro name devuelve coincidencias exactas y coincidencias parciales. No distingue entre mayúsculas y minúsculas. Esto solo devolverá la información de los canales que coincidan con el nombre proporcionado.

En este ejemplo, queremos buscar canales con "DevOps" en el nombre:

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

La API te permite consultar por ID de canal:

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

La API te permite consultar canales por ID de destino:

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

La API te permite realizar consultas por tipo de canal. La siguiente consulta devolverá todos los canales de correo electrónico de la cuenta elegida:

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

Crear un canal

Para crear un canal, se deben suministrar diferentes entradas para cada tipo de canal. Cada canal está conectado a un destino. Para obtener información sobre destinos, consulte el tutorial de NerdGraph sobre destinos.

Las mejores prácticas es usar el extremo channelSchema para ver qué campos deben enviarse bajo properties así:

{
  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 es un sistema de tickets configurable y, por lo tanto, no existe una forma estática de crear este canal.

Hay dos campos estáticos: project y issuetype.

Obtenga las sugerencias project y utilice uno de los valores como restricción para issuetype, como se muestra aquí:

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

Los valores elegidos se utilizarán como restricciones para recuperar el esquema:

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

Una vez que hayas obtenido cada campo y hayas elegido un valor de las sugerencias o como texto libre, puedes crear 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 es un sistema de tickets configurable y, por lo tanto, no existe una forma estática de crear este canal.

El esquema debe recuperarse como se muestra arriba, luego cada campo debe completarse con texto libre o mediante sugerencias:

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

Una vez que hayas obtenido cada campo y hayas elegido un valor de las sugerencias o como texto libre, puedes crear 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 propiedad payload es la carga útil que se enviará en la notificación. Utiliza la sintaxis del manillar para insertar dinámicamente información de la solicitud.

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

El eventSource debe ser la URL completa de un origen de evento existente. El eventContent es la carga útil que se enviará en el cuerpo de la notificación, como se muestra aquí:

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 tiene dos tipos de integración, nivel de servicio y nivel de cuenta. Para obtener más información, consulte los documentos de integración de PagerDuty.

Nivel de servicio:

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

Nivel de cuenta:

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

Actualizar un canal

Cuando actualiza un canal, tenga en cuenta que no necesita proporcionar todos los atributos del canal. Por ejemplo, si solo desea actualizar el nombre, ese es el único atributo que necesita actualizar, como se muestra aquí:

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

Probando un canal

Puede probar canales a través de la API NerdGraph. Esto se puede hacer antes o después de crear el canal.

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

Eliminar un canal

Puede eliminar canales a través de la API NerdGraph.

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

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

Tutorial NerdGraph: canales de inteligencia aplicada

Importante

Sugerencia

Listar y filtrar canales

Listado de todos los canales de una cuenta

Paginar a través de canales con paginación del cursor

Encuentra todos los canales por nombre

Buscar canal por ID

Buscar todos los canales por ID de destino

Encuentra todos los canales por tipo

Crear un canal

Atlassian Jira

ServiceNow (Incident-Management)

Slack

Webhook

Correo electrónico

AWS EventBridge

PagerDuty

Actualizar un canal

Probando un canal

Eliminar un canal

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

Tutorial NerdGraph: canales de inteligencia aplicada

Importante

Sugerencia

Listar y filtrar canales .css-21sua1{background:none;border:none;width:0;padding:0;}

Paginar a través de canales con paginación del cursor

Encuentra todos los canales por nombre

Buscar canal por ID

Buscar todos los canales por ID de destino

Encuentra todos los canales por tipo

Crear un canal

Atlassian Jira

ServiceNow (Incident-Management)

Slack

Webhook

Correo electrónico

AWS EventBridge

PagerDuty

Actualizar un canal

Probando un canal

Eliminar un canal

Listar y filtrar canales