Tutorial de NerdGraph: Canales de alertas

Además de gestionar su canal de alerta de notificación en la UI, puede emplear 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
    }
  }
}

Nota

La integración de Microsoft Teams ahora está disponible en las regiones de EE. UU. y la UE.

Requisitos previos

Antes de configurar New Relic para enviar notificaciones a Microsoft Teams, debes:

Tiene un canal de Microsoft Teams existente donde desea recibir notificaciones.

Cree un destino de Microsoft Teams en New Relic y obtenga el destinationId.

Paso 1: Obtener los ID de equipo disponibles

Sugerencia

Si ya conoce su ID de equipo y su ID de canal, puede omitir los pasos 1 y 2 e ir directamente al paso 3 para configurar el canal de notificación.

Esta consulta descubre qué Microsoft Teams son accesibles a través de su destino. Proporciona destinationId y especifica que desea ID de equipo (a través de key: "teamId"), y la API devuelve una lista de equipos disponibles con sus nombres e ID:

{
  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 respuesta contendrá una lista de equipos con sus nombres para mostrar e identificaciones de equipo únicas:

{
  "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": []
          }
        }
      }
    }
  }
}

Sugerencia

Si no ves el equipo que estás buscando en los resultados, puedes usar el parámetro filter para buscarlo por nombre:

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

Paso 2: Obtener los ID de canal disponibles para un equipo

Una vez que tenga un ID de equipo del Paso 1, esta consulta descubre qué canales existen dentro de ese equipo específico. Proporciona destinationId y teamId (como restricción), y la API devuelve una lista de canales disponibles con sus nombres e ID:

{
  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 respuesta contendrá una lista de canales dentro del equipo especificado:

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

Sugerencia

De manera similar a los ID de equipo, puedes filtrar canales por nombre usando el parámetro filter para buscar dentro del equipo especificado.

Paso 3: Configurar el canal de notificación de New Relic

Luego de obtener el ID del equipo y el ID del canal, configure el canal de notificación de New Relic para enviar alertas a su canal de Microsoft Teams.

Importante

Esta mutación crea un objeto de canal de notificación de New Relic que se conecta a un canal de Microsoft Teams existente. El canal de Teams ya debe existir en su espacio de trabajo de Microsoft Teams. Esta API no crea nuevos equipos o canales dentro de Microsoft Teams; solo configura New Relic para enviar notificaciones a sus canales de Teams existentes.

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

El parámetro product especifica el producto New Relic que genera la notificación. Los valores válidos incluyen:

IINT - inteligencia aplicada (incidente Intelligence)
ALERTS
ERROR_TRACKING
APM - monitoreo del rendimiento de aplicaciones (APM)
CHANGE_TRACKING
SECURITY
PD - Detección proactiva
Otros valores: CSSP, DISCUSSIONS, NTFC, SHARING

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 de NerdGraph: Canales de alertas

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

Equipos de Microsoft

Nota

Requisitos previos

Paso 1: Obtener los ID de equipo disponibles

Sugerencia

Sugerencia

Paso 2: Obtener los ID de canal disponibles para un equipo

Sugerencia

Paso 3: Configurar el canal de notificación de New Relic

Importante

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 de NerdGraph: Canales de alertas

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

Equipos de Microsoft

Webhook

Correo electrónico

AWS EventBridge

PagerDuty

Actualizar un canal

Probando un canal

Eliminar un canal

Listar y filtrar canales