PagerDuty APIの実行メモ

業務の中でPagerDuty APIを使用する機会がありました。
PagerDuty APIを使用してインシデントを更新する流れをまとめます！

PagerDutyとは？

まずは公式ドキュメントからの引用です。

PagerDuty（ペイジャーデューティ）はシステムのインシデント対応を一元化するプラットフォームです。システム障害対応に費やす時間を軽減し、貴重なエンジニアリソースをビジネス拡大に充てることができます。
https://www.pagerduty.co.jp/

自分の理解を交えて説明すると、企業や組織がシステムの障害や問題をすぐに検知し、適切な対応を取るためのアラート管理およびインシデント対応ツールといえます。
システムが問題を起こしたときなどに、インシデントとしてPagerDutyに集約、担当者への通知を自動で行ってくれます。

詳しい内容は省略しますが、興味のある方は公式サイト等をご覧ください。

PagerDuty API

PagerDutyは外部システムやアプリケーションからプログラムを使って操作できるようにするためのAPIが用意されています。
インシデント管理などをAPIを使って自動的に行うことが可能になります。

本記事では、PagerDuty APIを使用して実際にインシデントの更新を行ってみました。

実際にやってみた

まずはPagerDutyでインシデントを作成します。
Sample Incidentという名前で下図のようにインシデントを作成しました。このインシデントのインシデント名、Priority、UrgencyなどのパラメータをPagerDuty APIから更新します。

APIに送信するリクエストに必要な情報は、こちらのドキュメントから確認することができます。
今回はUpdate an incidentというAPIを使用してインシデントの更新を行います。

以下は公式ドキュメントのスクリーンショットです。

URLには https://api.pagerduty.com/incidents/{id} を指定すればよいことがわかります。
この{id}には何を指定するのか？という話ですが、確認方法はいくつかありますが、簡単なのはインシデントのURLから確認する方法です。アルファベット英数字からなる文字列がパスとして指定されています。これがインシデントIDです。また、URLからでなくても、インシデント情報を取得するAPIもあるので、確認も自動化することができます。

再度API referenceのドキュメントを確認します。以下の画像の通り、headerやbodyにも必須の値があります。requiredの記載がある項目ですね。

headersの”Accept”と”Content-Type”はデフォルトの値を使用します。ドキュメントに記載の通り、”application/vnd.pagerduty+json;version=2″と”application/json”の値を指定します。
“From”にはPagerDutyのアカウントで使用しているメールアドレスを指定します。
ドキュメント上は必須のheaderが3つのように見えますが、さらにAuthorizationヘッダにAPIアクセスキーを認証のために設定する必要があります。
APIアクセスキーはPagerDutyのIntegrationsタブ ＞ API Access Keysのページから作成・確認することができます。
Authorizationヘッダには”Token token=<API Access Key>“のような形式でヘッダを指定します。

続いてbodyの作成です。必須の項目は”incident”オブジェクトの”type”のみです。ここでは”incident_reference”と指定します。
今回はインシデント名、Priority、Urgencyのパラメータを更新するので、それぞれ値を指定します。インシデント名は任意の文字列、Urgencyには”high”または”low”の値を指定すればOKですが、Priorityには注意が必要です。
PriorityにはPriority IDと呼ばれる文字列を指定する必要がありますが、これはブラウザから確認できません。確認するにはList priorities APIを実行して確認する必要があります。

以上を踏まえて、次のようなPythonコードを作成しました。

import requests

target = "https://api.pagerduty.com/incidents/Q2CSVB2LMVDRV7"

headers = {
    'Accept': 'application/vnd.pagerduty+json;version=2',
    'Content-Type': 'application/json',
    'Authorization': 'Token token=<API Access Key>',
    'From': '<mail address>'
}

data = '\
{ "incident": {\
    "type": "incident_reference",\
    "title": "updated",\
    "urgency": "low",\
    "priority": {\
        "type": "priority_reference",\
        "id": "P2F1KGR"}\
} }'

response = requests.put(target, data=data, headers=headers)

print(response.status_code)
print(response.text)

インシデント名を”updated”に更新し、priorityをP1に更新(priority idはPagerdutyのアカウント毎に異なります)し、urgencyを”low”に更新します。これを実行します。

実行後、インシデントの画面を確認すると、、

インシデント名、Priority、urgencyの3項目がアップデートされました。
今回は例としてこの3項目を選択しましたが、インシデントのresolveや、エスカレーションポリシーの再割り当てなど様々な操作が可能です。

まとめ

実際のAPI操作を通してPagerDuty API操作を確認しました。
API Referenceを確認すれば大体実装の方法は確認できるものの、各オブジェクトの指定方法などは細かく言及されていなかったりもするので、試行錯誤しながらの実装になりました。。

参考になりましたら幸いです。