Tutorial NerdGraph: Canais de alertas

Além de gerenciar seu canal de alerta de notificação na interface, você pode utilizar nossa API NerdGraph.

Importante

Este documento refere-se ao uso API Nerdgraph para a nova plataforma de notificação usando destinos e mensagens de notificação. As mensagens de notificação também são chamadas de canais, que são diferentes do legado canal de notificação.

Dica

Para obter ajuda para começar a usar o NerdGraph, consulte Introdução ao NerdGraph.

Listar e filtrar canais

A consulta channels permite paginar todos os seus canais por conta. Também permite algumas funcionalidades de filtragem.

Aqui está um exemplo:

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

Para paginar seus canais, você deve solicitar o campo nextCursor na sua consulta inicial.

Com a paginação do cursor, você continua fazendo uma solicitação por meio do conjunto de resultados até que nextCursor retornado da resposta retorne vazio. Isso significa que você chegou ao fim dos seus resultados.

Aqui está um exemplo:

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

O código acima retorna um 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
          }
        }
      }
    }
  }
}

Portanto, em sua solicitação subsequente, forneça o cursor assim, até que ele fique vazio:

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

A API permite a consulta de canais por nome. O filtro name retorna correspondências exatas e parciais. Não faz distinção entre maiúsculas e minúsculas. Isso retornará apenas as informações dos canais que correspondem ao nome fornecido.

Neste exemplo, queremos encontrar canais com "DevOps" no nome:

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

A API permite consultar por ID do canal:

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

A API permite consultar canais por ID de destino:

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

A API permite consultar por tipo de canal. A consulta a seguir retornará todos os canais de e-mail da conta escolhida:

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

Crie um canal

Para criar um canal, devem ser fornecidas diferentes entradas para cada tipo de canal. Cada canal está conectado a um destino. Para obter informações sobre destinos, consulte o tutorial sobre destinos do NerdGraph.

As práticas recomendadas são usar o endpoint channelSchema para ver quais campos devem ser enviados em properties assim:

{
  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 é um sistema de tickets configurável e, portanto, não existe uma maneira estática de criar esse canal.

Existem dois campos estáticos - project e issuetype.

Busque as sugestões project e use um dos valores como restrição para issuetype, conforme mostrado aqui:

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

Os valores escolhidos serão usados como restrições para buscar o 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
        }
      }
    }
  }
}

Depois de buscar cada campo e escolher um valor nas sugestões ou como texto livre, você pode criar um 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 é um sistema de tickets configurável e, portanto, não há uma maneira estática de criar esse canal.

O esquema deve ser buscado conforme mostrado acima, então cada campo deve ser preenchido com texto livre ou utilizando sugestões:

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

Depois de buscar cada campo e escolher um valor nas sugestões ou como texto livre, você pode criar um 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
    }
  }
}

Observação

A integração do Microsoft Teams agora está disponível nas regiões dos EUA, UE e JP.

Pré-requisitos

Antes de configurar New Relic para enviar notificações ao Microsoft Teams, você deve:

Você já possui um canal no Microsoft Teams no qual deseja receber notificações?
Crie um destino do Microsoft Teams no New Relic e obtenha o destinationId.

Passo 1: Obter os IDs de equipe disponíveis

Dica

Se você já sabe o ID da sua equipe e o ID do canal, pode pular as etapas 1 e 2 e ir diretamente para a etapa 3 para configurar o canal de notificação.

Esta consulta descobre quais instâncias do Microsoft Teams estão acessíveis a partir do seu destino. Você fornece o destinationId e especifica que deseja os IDs das equipes (via key: "teamId"), e a API retorna uma lista de equipes disponíveis com seus nomes e IDs:

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

A resposta conterá uma lista de equipes com seus nomes de exibição e IDs de equipe exclusivos:

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

Dica

Se você não encontrar a equipe que procura nos resultados, pode usar o parâmetro filter para pesquisá-la pelo nome:

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

Etapa 2: Obtenha os IDs de canal disponíveis para uma equipe

Após obter o ID da equipe na Etapa 1, esta consulta descobre quais canais existem dentro dessa equipe específica. Você fornece destinationId e teamId (como uma restrição), e a API retorna uma lista de canais disponíveis com seus nomes e IDs:

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

A resposta conterá uma lista de canais dentro da equipe especificada:

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

Dica

Semelhante aos IDs de equipe, você pode filtrar canais por nome usando o parâmetro filter para pesquisar dentro da equipe especificada.

Etapa 3: Configure o canal de notificação do New Relic

Após obter o ID da equipe e o ID do canal, configure o canal de notificação do New Relic para enviar alertas para o seu canal do Microsoft Teams.

Importante

Essa mutação cria um objeto de canal de notificação do New Relic que se conecta a um canal existente do Microsoft Teams. O canal do Teams já deve existir no seu espaço de trabalho do Microsoft Teams. Esta API não cria novas equipes ou canais dentro do Microsoft Teams em si; ela apenas configura New Relic para enviar notificações aos seus canais existentes do Teams.

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

O parâmetro product especifica o produto New Relic que gera a notificação. Os valores válidos incluem:

IINT - inteligência aplicada (Inteligência de Incidentes)
ALERTS
ERROR_TRACKING
APM - monitoramento do desempenho de aplicativos (APM)
CHANGE_TRACKING
SECURITY
PD - Detecção proativa
Outros valores: CSSP, DISCUSSIONS, NTFC, SHARING

A propriedade payload é a carga que será enviada na notificação. Ele usa a sintaxe do guidão para inserir dinamicamente informações da solicitação.

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

O eventSource deve ser o URL completo de uma fonte de evento existente. O eventContent é a carga que será enviada no corpo da notificação, conforme mostrado aqui:

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 possui dois tipos de integração, nível de serviço e nível de conta. Para obter mais informações, consulte a documentação de integração do PagerDuty.

Nível de serviço:

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

Nível da conta:

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

Atualizar um canal

Ao atualizar um canal, observe que você não precisa fornecer todos os atributos do canal. Por exemplo, se você deseja atualizar apenas o nome, esse é o único atributo que você precisa atualizar, conforme mostrado aqui:

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

Testando um canal

Você pode testar canais por meio da API NerdGraph. Isso pode ser feito antes ou depois da criação do 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
  }
}

Excluir um canal

Você pode excluir canais por meio da API NerdGraph.

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

Esta tradução de máquina é fornecida para sua comodidade.

Importante

Dica

Listar e filtrar canais

Listando todos os canais de uma conta

Paginando através de canais com paginação de cursor

Encontre todos os canais por nome

Encontre canal por ID

Encontre todos os canais por ID de destino

Encontre todos os canais por tipo

Crie um canal

Jira Atlassiana

ServiceNow (Incident-Management)

Slack

Equipes da Microsoft

Observação

Pré-requisitos

Passo 1: Obter os IDs de equipe disponíveis

Dica

Dica

Etapa 2: Obtenha os IDs de canal disponíveis para uma equipe

Dica

Etapa 3: Configure o canal de notificação do New Relic

Importante

Webhook

E-mail

AWS EventBridge

PagerDuty

Atualizar um canal

Testando um canal

Excluir um canal

Esta tradução de máquina é fornecida para sua comodidade.

Tutorial NerdGraph: Canais de alertas

Importante

Dica

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

Paginando através de canais com paginação de cursor

Encontre todos os canais por nome

Encontre canal por ID

Encontre todos os canais por ID de destino

Encontre todos os canais por tipo

Crie um canal

Jira Atlassiana

ServiceNow (Incident-Management)

Slack

Equipes da Microsoft

Webhook

E-mail

AWS EventBridge

PagerDuty

Atualizar um canal

Testando um canal

Excluir um canal

Listar e filtrar canais