NerdGraph チュートリアル: アラートチャネル

UIで集計通知チャネルを管理するだけでなく、NerdGraph APIを使用することもできます。

重要

このドキュメントでは、宛先と通知メッセージを使用した新しい通知プラットフォームでのNerdgraphAPIの使用について説明します。通知メッセージはチャネルとも呼ばれ、従来の通知チャネルとは異なります。

ヒント

NerdGraphの使用を開始するためのヘルプについては、NerdGraphの概要を参照してください。

チャネルの一覧表示とフィルタリング

channelsクエリを使用すると、アカウントごとにすべてのチャネルをページ分割できます。また、いくつかのフィルタリング機能を許可します。

次の例を見てみましょう。

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

チャネルをページ分割するには、最初のクエリでnextCursorフィールドをリクエストする必要があります。

カーソルページネーションを使用すると、応答から返されるnextCursorが空に戻るまで、結果セットを介して要求を続けます。これは、結果の最後に到達したことを意味します。

次の例を見てみましょう。

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

上のコードは、次のような結果のセットを返します。

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

そのため、その後のリクエストでは、カーソルが空になるまで、このようにカーソルを提供します。

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

APIは、名前によるチャネルクエリを許可します。nameフィルターは、完全一致と部分一致を返します。大文字と小文字は区別されません。これにより、指定された名前に一致するチャネルの情報のみが返されます。

この例では、名前に"DevOps"が含まれるチャンネルを検索します。

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

APIを使用すると、チャネルIDでクエリを実行できます。

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

APIを使用すると、宛先IDでチャネルをクエリできます。

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

APIを使用すると、チャネルタイプでクエリを実行できます。次のクエリは、選択したアカウントのすべての電子メールチャネルを返します。

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

チャネルを作成する

チャネルを作成するには、チャネルタイプごとに異なる入力を指定する必要があります。各チャネルは宛先に接続されています。宛先については、宛先に関するNerdGraphチュートリアルを参照してください。

ベストプラクティスは、 channelSchemaエンドポイントを使用して、次のようにpropertiesで送信する必要のあるフィールドを確認することです。

{
  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は構成可能なチケットシステムであるため、このチャネルを静的に作成する方法はありません。

静的フィールドには、 projectとissuetypeの2つがあります。

次に示すように、 projectの提案を取得し、値の1つをissuetypeの制約として使用します。

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

選択した値は、スキーマをフェッチするための制約として使用されます。

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

各フィールドを取得し、提案から、またはフリーテキストとして値を選択した後、チャネルを作成できます。

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は構成可能なチケットシステムであるため、このチャネルを静的に作成する方法はありません。

上記のようにスキーマをフェッチしてから、各フィールドにフリーテキストを入力するか、提案を使用する必要があります。

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

各フィールドを取得し、提案から、またはフリーテキストとして値を選択した後、チャネルを作成できます。

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

payloadプロパティは、通知で送信されるペイロードです。ハンドルバー構文を使用して、リクエストから情報を動的に挿入します。

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

eventSourceは、既存のイベントソースの完全なURLである必要があります。eventContentは、次に示すように、通知の本文で送信されるペイロードです。

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には、サービスレベルとアカウントレベルの2種類の統合があります。詳細については、 PagerDuty統合ドキュメントを参照してください。

サービスレベル：

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

アカウントレベル：

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

チャネルを更新する

チャネルを更新するときは、チャネルのすべての属性を指定する必要はないことに注意してください。たとえば、名前のみを更新する場合は、次に示すように、それが更新する必要がある唯一の属性です。

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

チャネルのテスト

NerdGraphAPIを介してチャネルをテストできます。これは、チャネルの作成前または作成後に実行できます。

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

チャンネルの削除

NerdGraphAPIを介してチャネルを削除できます。

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

この機械翻訳は、参考として提供されています。

NerdGraph チュートリアル: アラートチャネル

重要

ヒント

チャネルの一覧表示とフィルタリング

アカウントのすべてのチャンネルを一覧表示する

カーソルページ付けを使用したチャネルのページ付け

名前ですべてのチャンネルを検索

IDでチャンネルを検索

宛先IDですべてのチャネルを検索

タイプ別にすべてのチャネルを検索

チャネルを作成する

アトラシアン Jira

ServiceNow（インシデント・マネジメント）

スラック

Webhook

メール

AWS EventBridge

PagerDuty

チャネルを更新する

チャネルのテスト

チャンネルの削除

この機械翻訳は、参考として提供されています。

NerdGraph チュートリアル: アラート チャネル

重要

ヒント

チャネルの一覧表示とフィルタリング .css-21sua1{background:none;border:none;width:0;padding:0;}

カーソルページ付けを使用したチャネルのページ付け

名前ですべてのチャンネルを検索

IDでチャンネルを検索

宛先IDですべてのチャネルを検索

タイプ別にすべてのチャネルを検索

チャネルを作成する

アトラシアン Jira

ServiceNow（インシデント・マネジメント）

スラック

Webhook

メール

AWS EventBridge

PagerDuty

チャネルを更新する

チャネルのテスト

チャンネルの削除

NerdGraph チュートリアル: アラートチャネル

チャネルの一覧表示とフィルタリング