Zendesk APIを使用してチケットを一括インポートする方法

Zendeskへのチケットデータ移行は、プラットフォームの切り替え、インスタンスの統合、または過去のレコードのインポートを行うチームにとって共通の課題です。Zendeskはいくつかのインポート方法を提供していますが、チケットインポートAPIは、過去のタイムスタンプを保持し、大規模なデータセットを適切に処理できる唯一のオプションです。

このガイドでは、Zendesk APIを使用してチケットを一括インポートする完全なプロセスについて説明します。データの構造化方法、エッジケースの処理方法、週末のプロジェクトを数週間の頭痛の種に変える可能性のある落とし穴の回避方法を学びます。

必要なもの

開始する前に、次のものが揃っていることを確認してください。

• Zendesk管理者アクセス：インポートAPIを使用できるのは管理者のみです。
• APIトークン：パスワード認証だけでは機能しません。Zendeskの管理設定から適切なAPIトークンが必要です。
• 既存のユーザー：リクエスターは、チケットをインポートする前にZendeskにすでに存在している必要があります。
• JSONの知識：REST APIリクエストとJSONペイロードを操作します。
• スクリプト環境：PythonまたはNode.jsを使用すると、バッチ処理がはるかに簡単になります。

複雑な移行なしでサポートワークフローを処理する簡単な方法をお探しの場合は、eesel AIのような最新のAIソリューションを既存のセットアップに直接統合できます。

Zendesk APIの一括チケットインポートエンドポイントについて

チケットインポートAPIは、標準のチケットAPIとはいくつかの重要な点で異なります。知っておくべきことは次のとおりです。

主なエンドポイントの違い

インポートエンドポイントはPOST /api/v2/imports/tickets（または最大100件のチケットのバッチの場合は/api/v2/imports/tickets/create_many）です。標準のチケット作成APIとは異なり、インポートエンドポイントは次のようになります。

• created_at、updated_at、solved_atなどの過去のタイムスタンプを保持します。
• クローズされたチケットのarchive_immediatelyパラメータをサポートします。
• インポート時にビジネスルールまたは自動化をトリガーしません。
• CCのユーザーに通知を送信しません。
• カスタムコメントのタイムスタンプを設定できます。

ソース：ZendeskチケットインポートAPIドキュメント

レート制限とバッチサイズ

Zendeskでは、一括インポートリクエストあたり最大100件のチケットが許可されています。大規模なデータセットの場合は、スクリプトにバッチ処理ロジックを実装する必要があります。標準のAPIレート制限が適用されるため（ほとんどのプランで1分あたり700件のリクエスト）、それに応じて移行を計画してください。

認証要件

すべてのインポートリクエストには、メールアドレスとAPIトークン（パスワードではありません）を組み合わせた基本認証が必要です。形式は{email_address}/token:{api_token}で、Base64でエンコードされます。

ステップ1：データを準備する

データ準備は、ほとんどの移行が成功するか失敗するかの分かれ目です。時間をかけて正しく行ってください。

必須フィールドとオプションフィールド

最小限、各チケットにはrequester_idとsubjectが必要です。完全な例を次に示します。

{
  "ticket": {
    "requester_id": 827,
    "subject": "アカウントアクセスに関するヘルプ",
    "description": "最初のチケットの説明",
    "assignee_id": 19,
    "tags": ["migration", "account-issue"],
    "created_at": "2023-06-25T10:15:18Z",
    "comments": [
      {
        "author_id": 827,
        "created_at": "2023-06-25T10:15:18Z",
        "value": "アカウントにログインできません"
      }
    ]
  }
}

ユーザーの前提条件

リクエスターとコメントの作成者は、Zendeskにアクティブなユーザーとしてすでに存在している必要があります。APIは、停止されたリクエスターまたは存在しないリクエスターを持つチケットを拒否します。一括CSVインポート（最大2,000行）またはUsers APIを使用して、最初にユーザーをインポートします。

添付ファイルの処理

添付ファイルには、2段階のプロセスが必要です。

1. 添付ファイルエンドポイントを使用してファイルをZendeskにアップロードし、アップロードトークンを取得します。
2. チケットインポートペイロードにそれらのトークンを含めます。

インライン画像（コメントのスクリーンショット）の場合、APIドキュメントではこれらが完全にカバーされていないことに注意してください。実際の移行では、インライン添付ファイルは標準の添付ファイルとは異なる処理が必要であることがわかります。

ステップ2：APIリクエストを構造化する

データの準備ができたら、実際APIリクエストの構築を開始できます。

基本的なリクエスト構造

基本的なインポートリクエストを構造化する方法を示すPythonの例を次に示します。

import requests
import base64

email = 'your-email@example.com'
api_token = 'your_api_token_here'
auth_string = base64.b64encode(f"{email}/token:{api_token}".encode()).decode()

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Basic {auth_string}'
}

ticket_data = {
    "ticket": {
        "requester_id": 827,
        "subject": "ヘルプ",
        "description": "説明",
        "created_at": "2023-06-25T10:15:18Z",
        "comments": [
            {
                "author_id": 827,
                "created_at": "2023-06-25T10:15:18Z",
                "value": "これはコメントです"
            }
        ]
    }
}

response = requests.post(
    'https://your-subdomain.zendesk.com/api/v2/imports/tickets',
    headers=headers,
    json=ticket_data
)

過去のコメントを含める

コメント配列は、個別のタイムスタンプを持つ複数のエントリをサポートします。これは、ソースシステムからの完全な会話履歴を保持するために重要です。

カスタムフィールドとタグ

ソースシステムのカスタムフィールドを、idとvalueのペアを持つcustom_fields配列を使用してZendeskカスタムフィールドにマッピングします。タグは、単純な文字列配列として渡すことができます。

ステップ3：特別なケースを処理する

実際の移行には、常にエッジケースが含まれます。最も一般的なケースの処理方法を次に示します。

クローズされたチケットのインポート

クローズされたステータスのチケットの場合は、archive_immediatelyクエリパラメータを使用します。

POST /api/v2/imports/tickets?archive_immediately=true

これにより、通常のチケットライフサイクルがバイパスされ、アーカイブに直接チケットが作成されます。Zendeskは、アクティブなチケットキューのパフォーマンスに影響を与えないように、750,000件以上の過去のチケットをインポートする場合は、このアプローチを推奨しています。

大規模なデータセットの管理

大規模な移行の場合は、次のプラクティスを実装します。

• チケットを100件のバッチで処理します（APIの最大値）。
• エラー追跡のために各バッチの結果をログに記録します。
• 失敗したリクエストのリトライロジックを構築します。
• オフピーク時にインポートを実行することを検討してください。

停止されたユーザーの処理

APIでは、リクエスターがアクティブなユーザーである必要があります。ソースデータに停止または削除されたユーザーからのチケットが含まれている場合は、2つのオプションがあります。

1. インポートする前にユーザーを再アクティブ化します。
2. 削除されたユーザーをプレースホルダーの「元従業員」アカウントにマッピングします。

ある移行チームは、これを痛いほど実感しました。「リクエスターと送信者が停止されている場合、APIは拒否します。インポートプロセス中に、元従業員を一時的に再アクティブ化する必要がありました。」

ソース：Zendeskコミュニティ移行エクスペリエンス

空のコメント本文

ZendeskのUIではこれが許可されていますが（誰かがテキストなしで添付ファイルをメールで送信する場合など）、APIは空の本文を持つコメントを拒否します。これらのケースでは、「（コメントテキストなし）」のようなプレースホルダーテキストを追加する必要があります。

ステップ4：実行と検証

データの準備が整い、エッジケースが処理されたので、インポートを実行する時が来ました。

バッチでリクエストを送信する

チケットデータを100件のチャンクでループし、各バッチを一括インポートエンドポイントに送信します。正常に作成されたチケットIDを含む、各バッチからの応答をログに記録します。

エラー処理

発生する可能性のある一般的なHTTPステータスコード：

• 200 OK：チケットが正常に作成されました。
• 422 Unprocessable Entity：検証エラー（JSON構造を確認してください）。
• 429 Too Many Requests：レート制限に達しました。指数バックオフを実装します。
• 401 Unauthorized：認証の問題。APIトークンを確認します。

検証戦略

インポート後、次の方法で成功を検証します。

• チケット数がソースデータと一致することを確認します。
• チケットをサンプリングして、タイムスタンプとコメントが正しくインポートされたことを確認します。
• 添付ファイルにアクセスできることを確認します。
• タグとカスタムフィールドが正しく表示されることをテストします。

一般的な落とし穴とその回避方法

他人の間違いから学ぶことで、大幅な時間を節約できます。移行チームが遭遇する最大の問題を次に示します。

リクエスターはアクティブである必要があります

前述のように、停止されたユーザーはインポートの失敗を引き起こします。最初に再アクティブ化するか、プレースホルダーアカウントを使用します。

インポートの順序が重要です

次の順序でインポートする必要があります。

1. 組織（使用している場合）
2. ユーザー
3. チケット

チケットはIDでユーザーと組織を参照するため、これらのレコードが最初に存在する必要があります。

メトリックとSLAは計算されません

ZendeskのメトリックとSLAは、インポートされたチケットでは計算されません。過去のデータに関するレポートが必要な場合は、「インポート済み」のようなタグを追加して、これらのチケットを現在のメトリックから除外することを検討してください。

チケットIDの予約なし

ソースシステムからのチケットIDの関係を保持することはできません。マージされたチケットと相互参照は、手動または外部マッピングテーブルを介して処理する必要があります。

サイドカンバセーションはサポートされていません

ソースシステムにサイドカンバセーションまたは共同スレッドがある場合、これらはAPIを介してインポートできません。これらを内部コメントに変換するか、このデータが転送されないことを受け入れてください。

JSON解析の癖

PowerShellを使用しているある移行チームは、予期しないJSON解析の問題に遭遇しました。「ZendeskはJSONを解析できないと文句を言いました。私が生成したJSONは構文的に正しかったのですが、PowerShellオブジェクトを直接渡しました。JSONを最初にファイルに保存してから、Zendeskに渡すと、問題なく動作しました。」

ソース：Zendeskコミュニティ移行エクスペリエンス

代替アプローチ：eesel AIおよびその他のオプション

APIが適切な選択ではない場合もあります。これらの代替手段を検討してください。

代わりにCSVインポートを使用する場合

Zendeskの一括CSVインポートは、ユーザーと組織（チケットではありません）で機能し、ファイルあたり最大2,000行を処理します。APIよりも簡単ですが、タイムゾーンのインポート、写真、言語設定、チケットサポートがないなど、大きな制限があります。

サードパーティの移行サービス

複雑な移行の場合、zendesk-import.comやZenplates Import Appのようなプロフェッショナルサービスが技術的な複雑さを処理できます。これらのサービスは通常、データ量に基づいて料金を請求しますが、開発時間を大幅に節約できます。

最新のAI搭載の代替手段

現在のヘルプデスクがニーズを満たしていないために移行する場合は、従来のプラットフォーム移行よりも最新のAIソリューションの方が適しているかどうかを検討してください。eesel AIはZendeskと統合して、完全なプラットフォームの切り替えを必要とせずに、AI搭載のチケット処理、自動応答、インテリジェントルーティングを追加します。

より良いサポートワークフローの構築を開始する

Zendesk APIを介してチケットを一括インポートすると、過去のデータ移行を正確に制御できますが、慎重な計画とエッジケースへの注意が必要です。主な手順は簡単です。データを徹底的に準備し、停止されたユーザーを処理し、バッチで処理し、その後すべてを検証します。

現在のサポートツールがニーズに対応できていないために移行を検討している場合は、eesel AIのZendesk統合がAI搭載の機能で既存のセットアップをどのように強化できるかを探ってください。または、カスタマーサポートへのまったく新しいアプローチを評価している場合は、eesel AIの価格をチェックして、最新のAIソリューションが従来のプラットフォーム移行とどのように比較されるかを確認してください。