NerdGraphチュートリアル通知チャンネル

NerdGraph APIを使用して、アラート通知チャネルを管理できます。

ヒント

NerdGraphおよびNerdGraphエクスプローラーの使用を開始するためのヘルプについては、 NerdGraphの概要を参照してください。

通知チャンネルの取得

notificationChannelsクエリを使用すると、アカウントごとにすべての通知チャネルをページ分割できます。 notificationChannelクエリを使用して、IDで特定の通知チャネルを取得することもできます。

ヒント

なお、特定のシークレットフィールド（例えば、パスワードやAPIキー）は、返されたフィールドの中で難読化されます。

この例では、指定されたアカウントIDのすべての通知チャネルのすべてのフィールドをページ制限200まで返します。インラインフラグメントを使用して、 AlertsNotificationChannelインターフェイスを実装する具象型の特定のフィールドを参照する方法に注意してください。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
            ... on AlertsXMattersNotificationChannel {
              config {
                integrationUrl
              }
            }
            ... on AlertsWebhookNotificationChannel {
              config {
                baseUrl
                basicAuth {
                  password
                  username
                }
                customHttpHeaders {
                  name
                  value
                }
                customPayloadBody
                customPayloadType
              }
            }
            ... on AlertsVictorOpsNotificationChannel {
              config {
                key
                routeKey
              }
            }
            ... on AlertsUserNotificationChannel {
              config {
                userId
              }
            }
            ... on AlertsSlackNotificationChannel {
              config {
                teamChannel
                url
              }
            }
            ... on AlertsPagerDutyNotificationChannel {
              config {
                apiKey
              }
            }
            ... on AlertsOpsGenieNotificationChannel {
              config {
                apiKey
                dataCenterRegion
                recipients
                tags
                teams
              }
            }
            ... on AlertsHipChatNotificationChannel {
              config {
                authToken
                baseUrl
                roomId
              }
            }
            ... on AlertsEmailNotificationChannel {
              config {
                emails
                includeJson
              }
            }
            ... on AlertsCampfireNotificationChannel {
              config {
                room
                subdomain
                token
              }
            }
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}

特定のアカウントの通知チャンネルのリストが200チャンネルのページ制限を超える場合、ページネーションカーソルを使って追加ページを取得することができます。

カーソルページネーションを使用すると、応答でそのフィールドが空になるまで、 nextCursorを使用して追加のページを要求し続けます。空のnextCursorは、結果セットの最後に到達したことを示します。

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

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}

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

{
  "data": {
    "actor": {
      "account": {
        "alerts": {
          "notificationChannels": {
            "channels": [
              {
                "id": "250",
                "name": "Channel 1",
                "type": "SLACK"
              },
              {
                "id": "713",
                "name": "Channel 2",
                "type": "WEBHOOK"
              },
              // ... +198 more notification channels in reality
            ],
            "nextCursor": "Wh4LK9JYzfACVlNkyvf7Rg==:I5VbSEpgx3UWNA5AOVsUPv4=",
            "totalCount": 268
          }
        }
      }
    }
  }
}

次のリクエストでは、このようにカーソルを提供し、カーソルが空になるまで、後続の各リクエストを更新して、更新されたカーソルを返します。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels(cursor: "Wh4LK9JYzfACVlNkyvf7Rg==:I5VbSEpgx3UWNA5AOVsUPv4=") {
          channels {
            id
            name
            type
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}

特定の通知チャネルのIDがある場合、APIを使用するとそれを直接検索できます。特定のチャネルはAlertsNotificationChannelインターフェイスを実装する具象型であるため、インラインフラグメントの... on構文を使用して特定のフィールドを指定する必要がある場合があることに注意してください。

この例では、Slackのチャンネルを取得しています。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannel(id: YOUR_CHANNEL_ID) {
          id
          name
          type
          ... on AlertsSlackNotificationChannel {
            config {
              teamChannel
              url
            }
          }
        }
      }
    }
  }
}

この例では、指定されたアカウントID上のすべての通知チャネルのID、名前、タイプと、そのチャネルに関連付けられているすべてのポリシーのリストを返します。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
            associatedPolicies {
              policies {
                id
                name
              }
              totalCount
            }
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}

通知チャンネルの作成

アラート通知チャネルを作成するためには、作成したい通知チャネルの具体的なタイプ（例えば、電子メール、Slackなど）と、その設定に必要な詳細（チャネルのタイプによって異なります）を知っておく必要があります。通知チャネルが作成されると、1つ以上の警告ポリシーに関連付けることができます。関連づけられたチャンネルは、条件に違反したときにそれらのポリシーからの通知を受け取ります。

注意

既存の通知チャネルタイプを照会することはできますが、作成できるのはそのサブセットのみです。具体的には、 user チャンネルタイプには編集可能なフィールドがなく、 Campfire と HipChat チャンネルタイプはどちらも非推奨です。

メール通知チャンネルのミューテーション作成例。

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    email: {
      emails: ["email@example.com"],
      includeJson: true,
      name: "Some Name <email@example.com>"
    }
  }) {
    notificationChannel {
      ... on AlertsEmailNotificationChannel {
        id
        name
        type
        config {
          emails
          includeJson
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

OpsGenie通知チャネルのcreate mutationの例です。

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    opsGenie: {
      apiKey: "api-key-from-opsgenie",
      dataCenterRegion: US,
      name: "OpsGenie notification channel name",
      recipients: ["user@example.com"],
      tags: ["tag1", "tag2"],
      teams: ["team1", "team2"]
    }
  }) {
    notificationChannel {
      ... on AlertsOpsGenieNotificationChannel {
        id
        name
        type
        config {
          apiKey
          teams
          tags
          recipients
          dataCenterRegion
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

PagerDutyの通知チャンネルのcreate mutationの例です。

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    pagerDuty: {
      name: "PagerDuty notification channel name",
      apiKey: "api-key-from-pagerduty"
    }
  }) {
    notificationChannel {
      ... on AlertsPagerDutyNotificationChannel {
        id
        name
        type
        config {
          apiKey
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

Slackの通知チャンネルのcreate mutationの例です。

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    slack: {
      name: "Slack notification channel name",
      teamChannel: "#team-channel",
      url: "https://hooks.slack.com/services/FAKE/MOREFAKE/IMAGINARYEXAMPLEURLCHUNK"
    }
  }) {
    notificationChannel {
      ... on AlertsSlackNotificationChannel {
        id
        name
        type
        config {
          teamChannel
          url
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

VictorOpsの通知チャンネルのcreate mutationの例です。

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    victorOps: {
      key: "example-api-key-from-victorops",
      name: "VictorOps notification channel name",
      routeKey: "example-route-key"
    }
  }) {
    notificationChannel {
      ... on AlertsVictorOpsNotificationChannel {
        id
        name
        type
        config {
          key
          routeKey
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

Webhook通知チャンネルのcreate mutationの例です。

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    webhook: {
      baseUrl: "https://example.com/webhook",
      basicAuth: {
        password: "t0t4lly-s3cr3t-p455w0rd",
        username: "webhook-user"
      },
      customHttpHeaders: [
        {name: "X-Api-Key", value: "100%-real-api-key"},
        {name: "X-Calling-Service", value: "New Relic Alerts"}
      ],
      customPayloadBody: "{ \"account_id\": \"$ACCOUNT_ID\", \"account_name\": \"$ACCOUNT_NAME\", \"closed_violations_count_critical\": \"$CLOSED_VIOLATIONS_COUNT_CRITICAL\", \"closed_violations_count_warning\": \"$CLOSED_VIOLATIONS_COUNT_WARNING\", \"condition_description\": \"$DESCRIPTION\", \"condition_family_id\": \"$CONDITION_FAMILY_ID\", \"condition_name\": \"$CONDITION_NAME\", \"current_state\": \"$EVENT_STATE\", \"details\": \"$EVENT_DETAILS\", \"duration\": \"$DURATION\", \"event_type\": \"$EVENT_TYPE\", \"incident_acknowledge_url\": \"$INCIDENT_ACKNOWLEDGE_URL\", \"incident_id\": \"$INCIDENT_ID\", \"incident_url\": \"$INCIDENT_URL\", \"metadata\": \"$METADATA\", \"open_violations_count_critical\": \"$OPEN_VIOLATIONS_COUNT_CRITICAL\", \"open_violations_count_warning\": \"$OPEN_VIOLATIONS_COUNT_WARNING\", \"owner\": \"$EVENT_OWNER\", \"policy_name\": \"$POLICY_NAME\", \"policy_url\": \"$POLICY_URL\", \"runbook_url\": \"$RUNBOOK_URL\", \"severity\": \"$SEVERITY\", \"targets\": \"$TARGETS\", \"timestamp\": \"$TIMESTAMP\", \"timestamp_utc_string\": \"$TIMESTAMP_UTC_STRING\", \"violation_callback_url\": \"$VIOLATION_CALLBACK_URL\", \"violation_chart_url\": \"$VIOLATION_CHART_URL\" }",
      customPayloadType: JSON,
      name: "Webhook notification channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsWebhookNotificationChannel {
        id
        name
        type
        config {
          customPayloadType
          customPayloadBody
          customHttpHeaders {
            value
            name
          }
          basicAuth {
            password
            username
          }
          baseUrl
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

xMattersの通知チャネルのクリエイトミューテーションの例です。

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    xMatters: {
      integrationUrl: "https://company.instance.xmatters.com/api/xm/v<version>/...",
      name: "xMatters notification channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsXMattersNotificationChannel {
        id
        name
        type
        config {
          integrationUrl
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

通知チャンネルの更新

アラート通知チャネルを更新するためには、変更したい通知チャネルの具体的なタイプ（たとえばメール、Slackなど）と、その設定に必要な詳細（チャネルのタイプによって異なります）を知っておく必要があります。他のGraphQL APIと同様に、チャネルのID以外の情報を知らなくても、チャネルの単一フィールドを更新することができます。

注意

既存の通知チャネルタイプを照会することはできますが、更新できるのはそのうちのサブセットのみです。具体的には、 user チャンネルタイプには編集可能なフィールドがなく、 Campfire と HipChat チャンネルタイプはどちらも非推奨です。

名前だけを更新するメール通知チャンネルの更新ミューテーションの例です。

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    email: {
      name: "Updated Name <email@example.com>"
    }
  }) {
    notificationChannel {
      ... on AlertsEmailNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

名前のみを更新するOpsGenie通知チャネルのアップデート・ミューテーションの例です。

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    opsGenie: {
      name: "OpsGenie updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsOpsGenieNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

PagerDutyの通知チャンネルで名前だけを更新する場合の更新ミューテーションの例です。

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    pagerDuty: {
      name: "PagerDuty updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsPagerDutyNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

Slackの通知チャンネルで名前だけを更新する場合の更新変異の例です。

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    slack: {
      name: "Slack updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsSlackNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

VictorOpsの通知チャンネルで、名前だけを更新する場合の更新変異の例です。

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    victorOps: {
      name: "VictorOps updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsVictorOpsNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

名前だけを更新するWebhook通知チャンネルの更新ミューテーションの例です。

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    webhook: {
      name: "Webhook updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsWebhookNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

xMattersの通知チャンネルで名前だけを更新する場合の更新ミューテーションの例です。

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    xMatters: {
      name: "xMatters updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsXMattersNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

通知チャンネルの削除

通知チャネルの削除は、アカウントIDとチャネルIDのみで可能です。チャネルを削除すると、すべてのポリシーから切り離され、そのチャネルには今後通知が送られなくなることに注意してください。

mutation {
  alertsNotificationChannelDelete(accountId: YOUR_ACCOUNT_ID,
  id: YOUR_CHANNEL_ID) {
    id
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

チャンネルをポリシーに関連付ける

アラート通知チャネルを作成するだけでは十分ではありません。チャンネルが作成されたら、それを1つ以上のポリシーに関連付ける必要があります。ポリシーに関連付けられると、そのポリシーの条件が違反したときに、チャネルはアラート通知を受け取ることができます。

この例では、2つのチャンネルと1つのポリシーを関連付けます。

mutation {
  alertsNotificationChannelsAddToPolicy(accountId: YOUR_ACCOUNT_ID,
    notificationChannelIds: [FIRST_CHANNEL_ID, SECOND_CHANNEL_ID],
    policyId: YOUR_POLICY_ID
  ) {
    notificationChannels {
      id
    }
    policyId
    errors {
      description
      errorType
      notificationChannelId
    }
  }
}

チャンネルとポリシーの分離

通知チャネルが耐用年数を過ぎた場合 (たとえば、引退した電子メールリストなど)、そのチャネルを、アラート通知を送信しているポリシー (またはポリシー) から切り離す必要が出てきました。この API コールは、チャネル自体はそのまま残しますが、指定されたポリシーからは削除します。

この例では、ポリシーから2つのチャンネルを削除し（他のチャンネルはそのまま）、その2つのチャンネルIDが削除されたことを確認しています。

mutation {
  alertsNotificationChannelsRemoveFromPolicy(accountId: YOUR_ACCOUNT_ID,
    notificationChannelIds: [FIRST_CHANNEL_ID, SECOND_CHANNEL_ID],
    policyId: YOUR_POLICY_ID
  ) {
    notificationChannels {
      id
    }
    policyId
    errors {
      description
      errorType
      notificationChannelId
    }
  }
}

ヒント

ポリシー からアラート通知チャネルを削除しても、他のポリシーで使用されている可能性があるため、 チャネルは削除されません。一方で、チャネルを削除すると、関連するすべてのポリシーがそのチャネルへのアラート通知の送信を停止します。

本書は、お客様のご参考のために原文の英語版を機械翻訳したものです。

NerdGraphチュートリアル通知チャンネル

ヒント

通知チャンネルの取得

ヒント

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

カーソルページネーションによる通知チャネルのページング

特定の通知チャネルをIDで検索

関連するポリシーを持つ通知チャネルのリスト

通知チャンネルの作成

注意

メール通知チャネルの作成

OpsGenieの通知チャンネルの作成

PagerDutyの通知チャンネルの作成

Slackの通知チャンネルの作成

VictorOpsの通知チャンネルの作成

Webhook通知チャンネルの作成

xMattersの通知チャンネルの作成

通知チャンネルの更新

注意

メール通知チャネルの更新

OpsGenie通知チャネルの更新

PagerDuty通知チャンネルの更新

Slackの通知チャンネルの更新

VictorOpsの通知チャンネルの更新

Webhook通知チャンネルの更新

xMatters通知チャネルの更新

通知チャンネルの削除

チャンネルをポリシーに関連付ける

チャンネルとポリシーの分離

ヒント