Zendesk APIでユーザーを作成する方法：完全ガイド

大規模なユーザーアカウントの管理は、最初は単純ですが、すぐに複雑になるタスクの1つです。新規買収からの顧客のオンボーディング、内部データベースからのユーザーの同期、またはセルフサービス登録フローの構築など、最終的にはZendesk（ゼンデスク）ユーザーをプログラムで作成する必要があります。

Zendesk Users API は、これを行うためのツールを提供します。これは、個々のユーザーの作成から、一度に数千人を一括インポートするまですべてを処理するRESTful（レストフル） APIです。このガイドでは、実際に動作させるための実践的な手順を、スタックに適応できる動作するコード例とともに説明します。

ユーザーの作成だけでなく、より多くのことを自動化したい場合は、eesel AI のようなツールを使用すると、チケットのルーティングからAI（人工知能）による応答まで、サポート自動化の全範囲を処理できます。

必要なもの

API（エーピーアイ）呼び出しを開始する前に、以下を確認してください。

• 管理者アクセス権を持つZendeskアカウント　管理者のみがAPIトークンを作成し、API経由でユーザーを管理できます。
• APIトークンまたはOAuth（オーオース）認証情報　これらを生成する方法については後述します。
• REST API（レストエーピーアイ）の基本的な知識　POST（ポスト）リクエストとは何かを知っておく必要があります。
• 開発環境　cURL（カール）、Python（パイソン）、またはNode.js（ノードジェイエス）で問題ありません。

ステップ1：API認証の設定

Zendesk（ゼンデスク）は、APIアクセス用にAPIトークンとOAuth（オーオース）の2つの主要な認証方法をサポートしています。ほとんどのサーバー間統合では、APIトークンの方が実装が簡単です。

APIトークンの生成

1. 管理者としてZendesk（ゼンデスク）アカウントにサインインします。
2. 管理センターに移動します（歯車アイコンをクリックし、「管理センターに移動」をクリックします）。
3. アプリと連携機能 → API → Zendesk APIに移動します。
4. 設定タブをクリックし、トークンアクセスが有効になっていることを確認します。
5. APIトークンタブに切り替え、APIトークンを追加をクリックします。
6. 「User Sync Integration（ユーザー同期連携）」のようなわかりやすい名前を入力します。
7. トークンをすぐにコピーします　Zendesk（ゼンデスク）は一度しか表示しません。

認証ヘッダーのフォーマット

Zendesk（ゼンデスク）は、APIトークンでBasic（ベーシック）認証を使用します。形式は次のとおりです。

• ユーザー名: /tokenが付加されたZendesk（ゼンデスク）のメールアドレス（例：you@company.com/token）
• パスワード: APIトークン自体

これらの認証情報をBase64（ベース64）でエンコードし、Authorization（オーソリゼーション）ヘッダーに含めます。

curl https://your-subdomain.zendesk.com/api/v2/users.json \ -u you@company.com/token:your_api_token_here

またはPython（パイソン）で：

import requests from requests.auth import HTTPBasicAuth subdomain = "your-subdomain" email = "you@company.com" token = "your_api_token_here" auth = HTTPBasicAuth(f"{email}/token", token) headers = {"Content-Type": "application/json"} url = f"https://{subdomain}.zendesk.com/api/v2/users.json" response = requests.get(url, auth=auth, headers=headers) print(response.json())

セキュリティのベストプラクティス

• APIトークンを環境変数に保存し、コードには絶対に保存しないでください。
• トークンを定期的にローテーションします　古いものを削除し、新しいものを生成します。
• 各トークンが何に使用されるかを把握できるように、わかりやすいトークン名を使用します。
• 連携機能が廃止されたら、トークンを削除します。
• 管理者のトークンを使用するのではなく、制限された権限を持つ専用のサービスユーザーを作成することを検討してください。

ステップ2：単一のユーザーを作成する

ユーザーを作成する最も簡単な方法は、POST /api/v2/usersエンドポイントを使用することです。少なくとも、名前を提供する必要があります。

必須およびオプションのパラメーター

ユーザーロールについて

Zendesk（ゼンデスク）には、3つの組み込みロールがあります。

• end-user: チケットを送信する顧客（ロールが指定されていない場合のデフォルト）
• agent: チケットを処理するサポートスタッフ
• admin: 完全な管理アクセス

Enterprise（エンタープライズ）プランの場合、custom_role_idパラメーターを使用して、カスタムエージェントロールを割り当てることもできます。カスタムロールは、最初に管理センターで作成する必要があることに注意してください　API経由で作成することはできません。

コード例

cURL（カール）：

curl https://your-subdomain.zendesk.com/api/v2/users.json \ -d '{"user": {"name": "Jane Smith", "email": "jane@example.com", "role": "end-user"}}' \ -H "Content-Type: application/json" \ -X POST \ -u you@company.com/token:your_api_token

Python（パイソン）：

import requests import json from requests.auth import HTTPBasicAuth subdomain = "your-subdomain" auth = HTTPBasicAuth("you@company.com/token", "your_api_token") headers = {"Content-Type": "application/json"} user_data = { "user": { "name": "Jane Smith", "email": "jane@example.com", "role": "end-user", "external_id": "user_12345" } } response = requests.post( f"https://{subdomain}.zendesk.com/api/v2/users.json", auth=auth, headers=headers, json=user_data ) if response.status_code == 201: user = response.json()["user"] print(f"Created user {user['id']}: {user['name']}") else: print(f"Error: {response.status_code} - {response.text}")

JavaScript（ジャバスクリプト）（Node.js（ノードジェイエス）とaxios（アクシオス）を使用）：

const axios = require('axios'); const subdomain = 'your-subdomain'; const email = 'you@company.com'; const token = 'your_api_token'; const userData = { user: { name: 'Jane Smith', email: 'jane@example.com', role: 'end-user', external_id: 'user_12345' } }; axios.post( `https://${subdomain}.zendesk.com/api/v2/users.json`, userData, { auth: { username: `${email}/token`, password: token }, headers: { 'Content-Type': 'application/json' } } ) .then(response => { const user = response.data.user; console.log(`Created user ${user.id}: ${user.name}`); }) .catch(error => { console.error('Error:', error.response?.data || error.message); });

レスポンスの解釈

作成が成功すると、ユーザーオブジェクトとともにHTTP 201 Created（作成済み）が返されます。

{ "user": { "id": 9873843, "name": "Jane Smith", "email": "jane@example.com", "role": "end-user", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "active": true, "verified": false } }

ステップ3：ユーザーの作成または更新（アップサート）

すでに存在するユーザーを作成しようとするとどうなりますか？標準の作成エンドポイントは422エラーを返します。外部システムから定期的にユーザーをインポートする同期シナリオでは、代わりにcreate_or_updateエンドポイントを使用します。

create_or_updateを使用する場合

以下の場合にPOST /api/v2/users/create_or_updateを使用します。

• 外部データベースからユーザーを同期している場合
• べき等な操作（同じリクエストで同じ結果が生成される）が必要な場合
• 作成前にユーザーが存在するかどうかを確認したくない場合

マッチングの仕組み

Zendesk（ゼンデスク）は、以下によってユーザーを照合します。

1. 外部ID　提供されている場合、これが優先されます。
2. メールアドレス　外部IDの一致が見つからない場合

レスポンスコード

実践的な例：外部システムからの同期

import requests from requests.auth import HTTPBasicAuth auth = HTTPBasicAuth("you@company.com/token", "your_api_token") headers = {"Content-Type": "application/json"} external_users = [ {"name": "Jane Smith", "email": "jane@example.com", "external_id": "usr_001"}, {"name": "John Doe", "email": "john@example.com", "external_id": "usr_002"} ] for external_user in external_users: user_data = {"user": external_user} response = requests.post( "https://your-subdomain.zendesk.com/api/v2/users/create_or_update.json", auth=auth, headers=headers, json=user_data ) if response.status_code == 201: print(f"Created: {external_user['email']}") elif response.status_code == 200: print(f"Updated: {external_user['email']}") else: print(f"Failed: {external_user['email']} - {response.text}")

ステップ4：複数のユーザーを一括で作成する

数百または数千のユーザーを作成する必要がある場合、個々のAPI（エーピーアイ）呼び出しは非効率的です。Zendesk（ゼンデスク）は、リクエストごとに最大100人のユーザーを受け入れる一括エンドポイントを提供します。

エンドポイントと制限

• エンドポイント: POST /api/v2/users/create_many
• 制限: リクエストごとに100人のユーザー
• 有効化: 一括インポートはZendesk（ゼンデスク）サポートによって有効にする必要があります（403エラーが発生した場合は、サポートに連絡してください）。

job_statusレスポンスについて

単一ユーザーの作成とは異なり、一括操作は非同期です。API（エーピーアイ）はjob_statusオブジェクトですぐに応答し、実際の作成はバックグラウンドで行われます。

{ "job_status": { "id": "82de0b044094f0c67893ac9fe64f1a99", "status": "queued", "total": 50, "progress": 0, "url": "https://your-subdomain.zendesk.com/api/v2/job_statuses/82de0b044094f0c67893ac9fe64f1a99" } }

ジョブステータスURL（ユーアールエル）をポーリングして、進行状況を追跡します。

def check_job_status(job_url): response = requests.get(job_url, auth=auth) job = response.json()["job_status"] print(f"Status: {job['status']}, Progress: {job['progress']}/{job['total']}") if job["status"] == "completed": for result in job.get("results", []): print(f" {result['action']}: User {result['id']} - {result['status']}") return job["status"] import time while check_job_status(job_url) != "completed": time.sleep(5)

一括処理が理にかなっている場合

一括作成の例

users_to_create = [ {"name": "User One", "email": "user1@example.com", "role": "end-user"}, {"name": "User Two", "email": "user2@example.com", "role": "end-user"}, # ... 最大100人のユーザー ] response = requests.post( "https://your-subdomain.zendesk.com/api/v2/users/create_many.json", auth=auth, headers=headers, json={"users": users_to_create} ) if response.status_code == 200: job = response.json()["job_status"] print(f"Job queued: {job['id']}") else: print(f"Error: {response.status_code} - {response.text}")

一般的なエラーとトラブルシューティング

適切なコードを使用しても、問題が発生する可能性があります。最も一般的な問題の処理方法を次に示します。

401 Unauthorized（認証されていません）

認証情報が無効です。確認してください：

• メールアドレスは正しいですか？
• ユーザー名に/tokenを追加しましたか？
• API（エーピーアイ）トークンはまだアクティブですか（削除されていませんか）？
• 正しいサブドメインを使用していますか？

403 Forbidden（禁止）

このアクションを実行する権限がありません。一般的な原因：

• API（エーピーアイ）トークンは管理者ではなく、エージェントに属しています。
• 一括インポートがアカウントで有効になっていません（Zendesk（ゼンデスク）サポートにお問い合わせください）。
• 十分な権限なしに管理者ユーザーを作成しようとしています。

422 Unprocessable Entity（処理できないエンティティ）

リクエストデータが無効です。確認してください：

• nameフィールドは存在しますか？（必須です）
• メール形式は有効ですか？
• ロールはend-user、agent、adminのいずれかですか？
• organization_idは存在しますか？

429 Too Many Requests（リクエストが多すぎます）

Zendesk（ゼンデスク）のレート制限に達しました。API（エーピーアイ）は、待機する秒数を示すRetry-Afterヘッダーを返します。コードに指数バックオフを実装します。

import time def api_call_with_retry(url, auth, headers, json_data, max_retries=3): for attempt in range(max_retries): response = requests.post(url, auth=auth, headers=headers, json=json_data) if response.status_code == 429: retry_after = int(response.headers.get('Retry-After', 60)) print(f"Rate limited. Waiting {retry_after} seconds...") time.sleep(retry_after) continue return response raise Exception("Max retries exceeded")

重複するメールエラー

「メールアドレスはすでに使用されています」という422エラーが表示された場合は、次のいずれかを行います。

• 代わりにcreate_or_updateエンドポイントを使用します。
• 最初にGET /api/v2/users/search?query=email@example.comでユーザーが存在するかどうかを確認します。

ユーザー管理自動化のベストプラクティス

Zendesk Users API（ゼンデスクユーザーAPI）を使用した後、一貫してうまく機能するパターンを次に示します。

べき等性にはexternal_idを使用する

常に、内部ユーザーID（アイディー）にマッピングするexternal_idを含めます。これにより、操作がべき等になり、同期が簡素化されます。

user_data = { "user": { "name": "Jane Smith", "email": "jane@example.com", "external_id": f"internal_db_{internal_user_id}" } }

確認ステータスを設定してメール確認をスキップする

信頼できるソース（独自のデータベースなど）からユーザーを作成する場合は、verified: trueを設定して、Zendesk（ゼンデスク）が確認メールを送信しないようにします。

user_data = { "user": { "name": "Jane Smith", "email": "jane@example.com", "verified": True # 確認メールをスキップ } }

カスタムロールを正しく処理する

カスタムロールはEnterprise（エンタープライズ）機能です。割り当てるには：

1. 最初に管理センターでカスタムロールを作成します。
2. ロールのURL（ユーアールエル）またはAPI（エーピーアイ）からcustom_role_idを取得します。
3. role: "agent"とcustom_role_id: 12345の両方を設定します。

適切なエラー処理を実装する

API（エーピーアイ）呼び出しが成功することを前提としないでください。呼び出しをtry/except（トライ/エクセプト）ブロックでラップし、特定のエラーケースを処理します。

try: response = requests.post(url, auth=auth, headers=headers, json=data) response.raise_for_status() except requests.exceptions.HTTPError as e: if response.status_code == 422: errors = response.json().get("details", {}) print(f"Validation error: {errors}") else: raise

認証情報を安全に保存する

API（エーピーアイ）トークンをハードコードしないでください。環境変数を使用します。

import os ZENDESK_SUBDOMAIN = os.environ.get("ZENDESK_SUBDOMAIN") ZENDESK_EMAIL = os.environ.get("ZENDESK_EMAIL") ZENDESK_TOKEN = os.environ.get("ZENDESK_TOKEN")

より広範な自動化のニーズを検討する

ユーザーの作成を自動化している場合は、サポート業務の拡大を管理している可能性があります。Zendesk API（ゼンデスクAPI）はユーザー管理を処理しますが、チケットの処理、ルーティング、および応答も自動化する必要がある場合があります。eesel AI はZendesk（ゼンデスク）と統合して、チケットの分類とタグ付けからAI（人工知能）による応答の作成まで、これらのワークフローを自動的に処理します。

Zendesk（ゼンデスク）ワークフローの自動化を開始する

これで、Zendesk（ゼンデスク）ユーザーをプログラムで作成するための基盤ができました。ユーザー同期連携の構築、オンボーディングの自動化、大規模な顧客ベースの管理など、Users API（ユーザーAPI）は必要な制御を提供します。

このガイドのパターン　認証、単一作成、アップサート、および一括操作　は、ほとんどの現実世界のシナリオをカバーしています。セットアップを検証するには、単一ユーザーのエンドポイントから開始し、スケールが増加したら一括操作に移行します。

ユーザーの作成を超えて自動化したい場合は、AI（人工知能）がサポートワークフロー全体をどのように合理化できるかを検討してください。eesel AI はZendesk（ゼンデスク）と統合して、チケットのトリアージ、応答の作成、インテリジェントなルーティングを処理し、手作業を減らしながら応答時間を改善します。カスタマーサービス向けのAIエージェント を調べて、自動化がサポートスタック全体にどのように拡張できるかを確認できます。