開発ガイド主要な開発バックエンド
本ドキュメントでは、開発者がロールに応じて使い分けるべき 3 つの主要な操作プラットフォームを明示しています。開発者バックエンド
DingTalk 開発者バックエンドは、アプリ開発を管理するためのサービスプラットフォームです。開発者はアプリ情報の設定やアプリの稼働状況の確認などを行えます。管理者バックエンド
DingTalk 管理者バックエンドは、組織管理者が組織構成、ユーザー権限、ワークベンチ設定を管理するためのコアプラットフォームです。このバックエンドを通じて、管理者は連絡先のインポート、承認フローの設定、サブ管理者への権限付与などの操作を行えます。コアな ID 体系
DingTalk 開発において、「誰か」と「どのアプリか」を区別することは非常に重要です。本ドキュメントでは以下の主要な ID を定義しています。CorpId
DingTalk における企業組織の一意の識別子を表します。ほとんどの企業向け API を呼び出す際には、必ずこの ID を用いて認証する必要があります。 確認パス：DingTalk 開発者バックエンドにログインし、ホームで企業のCorpId を確認します。
UserId
社内の具体的な社員の一意の識別子を表します。チャット送信、プロファイル照会、承認などの API で使用され、変更できません。 確認パス：DingTalk 管理者バックエンドにログインし、連絡先 > メンバー管理ページで社員の名前をクリックすると、社員のUserId を確認できます。
UnionId
ユーザーのアプリ横断統一識別子です。同一ユーザーは同一のオープンプラットフォームアカウント配下のすべてのアプリで同じ UnionId を持ち、アプリ間でのデータ連携に使用されます。 確認パス：ユーザーの userId を用いてユーザー詳細の照会 API を呼び出し、unionid パラメータの値を取得します。
Unified App ID
DingTalk がすべての種類のアプリに割り当てるグローバル一意の ID で、システム間連携の簡素化を目的とし、従来の AgentId/AppId 体系を段階的に置き換えるものです。 確認パス：DingTalk 開発者バックエンドにログインし、アプリ詳細に入った後、認証情報とベーシック情報で確認します。AgentId
社内アプリ（H5、ミニプログラムなど）の機能識別子です。主にワークベンチ管理 API（ホーム設定など）で使用されます。 確認パス：- 社内アプリのウェブアプリ AgentId
- 社内アプリのミニプログラム AgentId
安全な認証情報と権限（Auth 体系）
この部分は開発において最もミスが起きやすい箇所で、API 呼び出しの認証およびサイレントログインのロジックに関わります。Client ID/Client Secret
- 定義：アプリの認証情報のペア（ユーザー名とパスワードに類似）。
- 用途：
access_tokenを取得するために使用され、社内アプリとサードパーティアプリの両方でこの仕組みを使用します。 - 注意：
Client Secretは秘密鍵であるため、適切に保管し、漏洩させてはいけません。 - 取得方法：DingTalk 開発者バックエンドで社内アプリまたはサードパーティ社内アプリを作成すると、システムが自動的に Client ID と Client Secret のペアを生成します。
説明
社内アプリをサービスプロバイダーに開発委託する場合、サービスプロバイダーは CustomKey と CustomSecret に基づいて権限付与を取得する必要があります。access_token
- 定義：OpenAPI を呼び出すための「チケット」。
- 用途：保護された API を呼び出すたびに、正当性を検証するためにこの認証情報を持参する必要があります。
- 注意：有効期間は通常 7200 秒（2 時間）で、有効期間内に繰り返し取得すると自動的に延長されます。
-
取得方法：
- 社内アプリの場合、社内アプリのアクセストークンを取得する API を呼び出して access_token を取得します。
- サードパーティ社内アプリの場合、サードパーティアプリ認可企業のアクセストークンを取得する API を呼び出して access_token を取得します。
-
差異：
- 社内アプリの
access_tokenは、そのアプリが申請したすべての権限を持ちます。 - サードパーティアプリの
access_tokenの権限は、企業の認可範囲に制限されます。
- 社内アプリの
authCode
定義：ユーザー身元認証のための主要な認証情報。 用途：ユーザーの身元情報（userid など）と引き換えるために使用します。
注意：有効期間はわずか 5 分間で、一度使用すると失効し、再利用できません。
取得方法：getAuthCode、requestAuthCode などの API を呼び出して取得します。詳細な使い方は本人認証（サイレントログイン）を参照してください。
jsapi_ticket
定義：フロントエンドの JS API の署名を生成するために使用します。 用途：H5 マイクロアプリが DingTalk の提供する各種 JSAPI 機能（ユーザー情報の取得、チャットの開始、ネイティブコンポーネントの呼び出しなど）を安全に呼び出すために必要です。 注意：有効期間は 2 時間に設定されており、期限切れまたはパラメータの不一致により「jsapi ticket 読取失敗」や「署名検証失敗」などのエラーが発生します。 取得方法：access_token を使用して jsapiTicket を取得する API を呼び出して取得します。
クイックスタート
以下の擬似コードは、CorpId と access_token を使用して最もシンプルな API 呼び出しを行い、環境設定が正しいかを検証する方法を示しています。
- 認証情報の取得：
Client IDとClient Secretを使用して API を呼び出し、access_tokenを取得します。 - パラメータの準備：管理者バックエンドで任意のメンバーの
UserIdを取得します。 - パラメータの置換：上記のリクエストを構築し、
ACCESS_TOKENとUSERIDを置換します。 - テストの実行：
"errcode": 0, "errmsg": "ok"が返れば設定成功となり、その後の開発を続けられます。
お知らせ：実際の開発では HTTPS を使用し、エラーハンドリングとリトライ機構を適切に実装してください。