PagerDutyのCSVユーザーインポートをやってみた

こんにちは。たかやまです。

PagerDutyに複数のユーザーを登録する際、管理画面から1人ずつ手動で登録するのは時間がかかりますよね。

そこで今回は以下のドキュメントに記載されているPagerDutyの公式スクリプトimport_users.rbを使ったCSV一括ユーザーインポートの方法を紹介します。

https://support.pagerduty.com/main/lang-ja/docs/import-users-from-a-csv

クイックスタート

すぐに試したい方向けの手順はこちらです。
パラメーター詳細は「やってみた」セクションをご確認ください。

# 1. スクリプトをダウンロード
curl -O https://raw.githubusercontent.com/PagerDuty/public-support-scripts/master/import_users/import_users.rb

# 2. 依存関係をインストール
cat > Gemfile << 'EOF'
source "https://rubygems.org" do
  gem "faraday"
end
EOF
bundle install --path vendor/bundle

# 3. CSVファイルを準備（user.csv）
# フォーマット: name,email,role,title,country_code,phone_number,teams,team_roles
# 例: 山田太郎,yamada.taro@example.com,user,Engineer,81,9012345678,Platform Team,admin

# 4. スクリプト実行
bundle exec ruby import_users.rb \
  -a YOUR_GLOBAL_API_KEY \
  -f user.csv \
  -e requester@example.com

やってみた

以下の手順をもとに実際にやってみたいと思います。

https://support.pagerduty.com/main/lang-ja/docs/import-users-from-a-csv

前提条件としてユーザー追加をするユーザーは Global Admin 以上の権限が必要です。

APIトークンの取得

使用するAPIトークンはユーザーAPIトークンではなくグローバルAPIキーを使用してください。

注: このスクリプトは、グローバルAPIキー（個人/ユーザーAPIキーではなく）を使用して実行する必要があります。個人APIトークンを使用すると、このユーザーは作成されたすべてのチームに追加されます。

https://github.com/PagerDuty/public-support-scripts/blob/master/import_users/README.md?plain=1#L1-L3

APIキーは「Integrations」 > 「API Access Keys」から取得します。

APIキーはユーザーを作成するので Read-only API key はオフにします。

一度ページを離れると再取得できないため、安全な場所に保存してください。

CSVファイルの準備

CSVファイルを準備します。CSVフォーマットは以下の8カラムで構成されます。

name,email,role,title,country_code,phone_number,teams,team_roles

APIの値とコンソール上で見るユーザーロール名は対にはなっておらず、以下の対応表を参考に必要なユーザーロールのAPIの値を設定する必要があります。

ロールを指定しない場合、デフォルトでManager(user)が設定されます。

参考: Roles in the REST API and SAML - PagerDuty

CSVファイルのサンプルは以下の通りです。

山田太郎,taro.yamada@example.com,admin,Administrator,,,
鈴木花子,hanako.suzuki@example.com,user,Operations Engineer,81,09012345678,
佐藤次郎,jiro.sato@example.com,observer,Operations Engineer,81,09012345678,Team A;Team B,limited_user;limited_user

スクリプトのセットアップ

まず、公式スクリプトをダウンロードします。

curl -O https://raw.githubusercontent.com/PagerDuty/public-support-scripts/master/import_users/import_users.rb

公式リポジトリ: import_users.rb - GitHub

次に、Faradayライブラリをインストールします。環境を汚さないように--pathオプションでプロジェクトローカルにインストールします。

# Gemfileを作成
cat > Gemfile << 'EOF'
source "https://rubygems.org" do
  gem "faraday"
end
EOF

# プロジェクトローカル（vendor/bundle）にgemをインストール
bundle install --path vendor/bundle

スクリプト実行

準備が整ったら、スクリプトを実行します。

bundle exec ruby import_users.rb \
  -a YOUR_GLOBAL_API_KEY \
  -f user.csv \
  -e requester@example.com

各オプションの説明

• -a（PagerDutyのグローバルAPIキー）
• -f（CSVファイルのパス）
• -e（リクエスト者のメールアドレス）
• -nまたは--no-new-teams（存在しないチーム名が指定された場合スキップする[オプション])

実行時には、サブドメインの確認プロンプトが表示されます。

About to perform user import for your-subdomain, proceed? (y/n)

yを入力するとインポートが開始されます。

実行結果の確認

スクリプト実行中、以下のような出力が表示されます。

Adding user: 山田太郎.
Added user with ID XXXXXXXX.
Adding user to teams.

既存ユーザーの場合は、以下のように表示されます。

Found user: yamada.taro@example.com.
Found contact methods: ...

スクリプト実行時の注意点

他スクリプトを使用する際の注意点をまとめておきます。

• CSVファイルにヘッダー行は不要
  • スクリプトは各行を配列インデックス（0から7）で直接処理します
  • ヘッダー行があると最初のユーザーとして処理されエラーになります
• 既存ユーザーは上書きされない
  • 同じメールアドレスのユーザーが既に存在する場合、そのユーザーはスキップされます
  • 新規ユーザーのみがインポートされます
• チーム名が存在しない場合の動作
  • デフォルトでは、存在しないチーム名が指定されている場合、新しいチームが自動作成されます
  • チームの自動作成を防ぎたい場合は、--no-new-teamsオプションを使用してください
• 電話番号の国コード形式
  • 国コードは数値形式で指定します（例: 日本は81）
  • 電話番号と国コードの両方が必要です
• タイトルにカンマが含まれる場合
  • タイトルにカンマが含まれている場合、CSVのパースエラーが発生する可能性があります
  • その場合、確認プロンプトが表示されるので、内容を確認してから進めてください
• ユーザー作成時に招待メールが自動送信される
  • REST APIの仕様により、ユーザー作成と同時に招待メールが送信されます
  • 招待メールの送信を避けたい場合は、メールアドレスに.invalidを付けてインポートし、後から一括更新する方法があります
• チーム名に使用できない文字がある
  • \、/、&、<、>および非印刷文字はチーム名に使用できません

最後に

今回はPagerDutyの公式スクリプトimport_users.rbを使ったCSV一括ユーザーインポートの方法を紹介しました。

大量のユーザーを一度に登録する必要がある場合、この方法を使うことで効率的にユーザー管理ができるようになります。

特に組織変更時や新規プロジェクト立ち上げ時など、多くのユーザーを登録する必要があるシーンで役立つと思います。

Terraformに慣れている方であれば、公式プロバイダーによるユーザー管理リソースが提供されているため、より柔軟かつ管理しやすい方法としてTerraformでの管理もおすすめです。

https://registry.terraform.io/providers/PagerDuty/pagerduty/latest/docs/resources/user

この記事がどなたかの参考になれば幸いです。

以上、たかやま(@nyan_kotaroo)でした。