NerdGraphチュートリアル：適用されたインテリジェンスチャネル

UIで適用されたインテリジェンス通知チャネルを管理することに加えて、NerdGraphAPIを使用できます。

重要

このドキュメントでは、宛先と通知メッセージを使用した新しい通知プラットフォームでの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: "") {
          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

チャネルを更新する

チャネルのテスト

チャンネルの削除