自分の初のQiita記事なので、カジュアルな感じで書いてみたいと思います。

簡単な自己紹介

PagerDuty Japanに入社して1年ちょっと経ったリナルディと申します。本名を10回言ったら、舌を噛んでしまうため、略して、社内で「リンさん」と呼ばれています。

インドネシア出身で、画像処理や大手通販会社の銀行事業のバックエンド、エナジー事業のエンジニア・エンジニアリーダーとして活動してから、ServiceNow社のTechnical Consultantとして働いており、数年経った後、PagerDuty社にProfessional Services Consultantとして入社し、ジムのパーソナルトレーナーのように、各々のお客様の要望・目指したいことに合わせ、PagerDutyのベストプラクティスに沿って、PagerDutyの適切な使い方を案内・提案し、技術的支援をしており、お客様の目指す目標に向けて、お客様と共に走って参ります。

日本語が母語ではないため、変な表現があれば、大目に見て頂ければ幸いです。🙇

はじめに

PagerDutyのAPIが２種類あって、Event API と REST APIがあり、実は、両方 RESTful API なので、区別がなかなか難しいので、それぞれについてや、役割、使い方、違いなどについて、簡単に解説したいと思います。

PagerDuty Event API（以下、Event APIという）

🚀 Event APIって何？

Event APIは、要するにPagerDutyにお知らせする緊急ブザーみたいなものです。サーバーがダウンした？アプリでバグ発見？これらの情報をPagerDutyに送るときだけに使います。後、システムに何か変わったことがある時に、その変更情報を送るときだけにも使います。

🔧 どうやって使うの？

アラート発信: 何か問題があったら、PagerDutyに「ヘルプ！」と叫ぶ。
問題解決: 問題が解決したら、PagerDutyに「大丈夫、もう大丈夫だよ」と伝える。
変更履歴: 変更があったら、PagerDutyに「これが変わったよ」と教える。

備考
PagerDutyに「ヘルプ！」を叫びたい時に、Event APIを呼び出す時に、リクエスト（JSON形式）の「event_action」キーに trigger という値に設定し、送信して、「大丈夫、もう大丈夫だよ」と伝えたい時に、「event_action」キーに resolve という値に設定し、送信してください。

🌟 いつ使うのがベスト？

サーバーの監視ツールが「おっと、何かおかしいぞ」と教えてくれた時。
自分の作ったアプリが予期せぬ挙動をした時。
システム変更があって、その変更をPagerDutyに知らせる時。

💡 Event APIのいいところ

自分やチームがすぐに問題をすぐに知れるようになること。
自動でアラートを出せるので、夜中でも安心。
色んな監視ツール側でのEvent APIを呼び出す設定が楽チン。
Event APIを使うと、問題対応によく使う情報が付いてくる（参考）

🏁 いざ、Event APIを使ってみよう！

手始めに Integration Keyをゲット！
まずはPagerDutyでEvent Integration Keyを作成。これがあれば、APIとの会話が始まるぜ！
イベントトリガーを仕掛けよう
次に、監視ツールをセットアップ。システムがおかしくなったら、すぐにPagerDutyに教えてくれるようにしておくんだ。
APIリクエストを飛ばすぞ！
何か問題が起きたら、さっとAPIリクエストをPagerDutyに送信。データを丁寧にパッケージングして、必要なら、追加情報も追記してね。
通知が来たら行動開始！
PagerDutyがチームに通知を送るから、受け取ったら即座に対応だ！

🚨 注意点

Event APIを一気にたくさん叩くと、PagerDutyも困ってしまうので、使いすぎには注意。
参考
- PagerDuty - Event APIのRate Limitについて
何か問題があった時にちゃんと対応できるように、エラー処理もバッチリしときましょう。
Event APIは、基本的には何か発生した時に、PagerDutyに知らせるために特化したもの なので、POSTリクエストしか受け付けられない

簡単に言うと、Event APIはあなたのサーバーやアプリの監視役。何かあったらすぐに教えてくれる頼もしい存在です。これで、システムの問題に素早く対処できますね！👍

PagerDuty REST API（以下、REST APIという）

🔍 REST APIって何？

REST APIはPagerDutyの万能リモコンみたいなもの。ユーザーやチームの設定を変えたり、インシデントの履歴をチェックしたり、いろいろな操作ができます。

🛠️ 具体的には何ができるの？

チーム管理: チームメンバーを追加したり、役割を変えたり。
インシデント管理: インシデントの詳細を見たり、状態を更新したり。
レポート取得: 過去のアラートやインシデントのデータを集めたり。

🌈 REST APIの便利なところ

いろいろな設定やデータが一括で管理できるので、PagerDutyをもっとパワフルに使えます。
自動化やカスタマイズがしやすくなるので、自分のワークフローにぴったり合わせられます。

🚀 いつ使うのがベスト？

PagerDutyで何かを設定したいとき。
過去のアラートやインシデントのデータが必要なとき。
自分のシステムやアプリとPagerDutyをスムーズに連携させたいとき。

🏁 REST API を使ってみよう！

API Keyをゲット
まずは下記のいずれの方法で、PagerDutyでREST API Keyを作成。これがあれば、後はAPIとの会話がスタートできるよ！
- 一般的アクセス用REST API Key（参考)
  備考：万能なので、全設定に対して、間違って変更したり、削除したりできてしまうので、使用時に要注意
- ユーザートークンAPI Key（参考)
  備考：権限はそのユーザー自身ができることに限るので、そのユーザーに権限のない操作ができないので、使用時に注意
- スコープAPI Key（参考)
  備考：変幻自在にできることを設定可能ですが、有効期限があるので、切れたら、また再作成が必要
APIでデータを自在に操ろう
REST APIを使えば、インシデントの情報やユーザー設定、オンコールスケジュールなど、あらゆるデータを取得・更新可能。データの取得だけでなく、変更も思いのまま！
自動化でラクラク管理
このAPIを活用して、面倒なインシデント管理や設定変更を自動化。プログラミングスキルを使って、手間を減らそう。
カスタマイズで快適に
通知の内容やタイミングを自分たちのワークフローに合わせてカスタマイズ。必要な情報だけを、適切なタイミングで受け取れる。

👀 注意点

REST APIは強力だけど、使い方を間違えると大変なことになる可能性も。しっかりとドキュメントを読んで正しく使いましょう。
Event APIと同じように、REST APIを一気にたくさん叩くと、PagerDutyも困ってしまうので、使いすぎには注意。(参考)
データを扱うときは特に慎重に。間違った操作で大事な情報を変えてしまわないように気をつけてくださいね。

注意
一般アクセス用REST API Keyを生成した際に「Read-Only API Key」にチェックを付け、作った場合、GETリクエストしか受け付けられないし、オブジェクト作成・更新・削除ができないので、要注意。

ざっくり言うと、REST APIはPagerDutyの中のデータや設定を自在に操れるスーパーツール。これを使いこなせば、PagerDutyがもっと便利で強力なツールに変身します！ 🌟

まとめ

🚨 Event APIって？

主役はアラート: これはあなたのシステムやアプリからPagerDutyに「ヘルプ！何か問題が起きてる！」って伝える役割を持っています。
インシデントを管理: 問題が発生したときに、インシデントを作成したり、解決したり、ステータスを更新したりします。
自動通知の達人: 監視ツールが何か異常を察知したら、自動的にPagerDutyに知らせてくれます。

⚙️ REST APIって？

万能リモコン: これはPagerDutyのあらゆる設定や情報にアクセスして、管理や更新ができるツールです。
データと設定のマエストロ: ユーザーやチームの設定変更、インシデントの履歴チェック、レポートの取得など、いろいろなことができます。
カスタマイズの達人: 自分のワークフローに合わせて、PagerDutyを自在にカスタマイズできます。

🌟 どう使い分ける？

Event API: 「今すぐ何か対応して！」という緊急のアラートや通知を送るときに使います。問題発生時のファーストレスポンダーですね。アラートや変更情報をPagerDutyに送る時にこれを使ってくださいね。
REST API: 日々の設定変更やデータの確認、報告書の作成など、もっと計画的で管理的なタスクに使います。バックオフィスのプロです。

要するに、Event APIはあなたのシステムやアプリからのSOS信号をPagerDutyに伝える役割、REST APIはPagerDutyの設定やデータを管理・操作する役割を担っています。この２つを上手く使い分けることで、PagerDutyをもっと効果的に活用できますよ！💡🎉

参考リソース