API 呼び出し手順の詳細

本ガイドは、開発者がゼロから DingTalk オープンプラットフォームの API を呼び出し、アプリの新規登録から API の疎通までの全プロセスを完了できるよう支援することを目的としています。主要な手順、コード例、注意事項、デバッグ方法を網羅し、開発者がクイックスタートで API を呼び出せるようサポートします。

本例では社内アプリをベースに、API を呼び出して連絡先内のユーザーの詳細情報を取得する流れを説明します。他のアプリタイプの場合も、本ドキュメントを参考にできます。

事前準備

ベーシック概念：DingTalk オープンプラットフォームのベーシック概念および各製品ブロックのドキュメント説明を理解していること。詳細はベーシック概念のドキュメントを参照してください。
API レート制限：API のレート制限を理解していること。詳細は呼び出し回数とレート制限のドキュメントを参照してください。
開発者権限：開発者バックエンドのサブ管理者および開発者権限を有していること。または、DingTalk 開発者にログインして新規ユーザーの新規登録とアクティベーションを完了することも可能です。
ユーザー UserId の取得：DingTalk 管理バックエンドにログインし、連絡先 > メンバー管理 で UserId を確認します。詳細はベーシック概念の説明を参照してください。

ステップ 1：DingTalk アプリを作成する

開発者バックエンドにアクセスし、アプリ開発 > DingTalk アプリ > アプリの作成 をクリックします。

説明

アプリ情報を入力し、保存をクリックします。

設定項目	必須	設定の説明
アプリ名	はい	アプリ名を入力します。アプリ名の最小文字数は 2 文字です。
アプリの説明	はい	アプリが提供する製品またはサービスを簡潔に記述します。説明の最小文字数は 4 文字です。
アプリアイコン	いいえ	アプリアイコンをアップロードします。アイコンは JPG/PNG 形式、240 px * 240 px 以上、1:1 の比率、2 MB 以内、角丸なしのものを使用してください。

アプリ詳細ページに進み、ベーシック情報 > 認証情報とベーシック情報 で、アプリ認証情報とベーシック情報を確認します。
アプリの Client ID と Client Secret を保存し、後続の API 呼び出しで使用します。

説明

Client ID と Client Secret の取得方法はベーシック概念の説明を参照してください。取得後は厳重に保管し、漏洩を防いでください。

ステップ 2：権限を設定する

必要な権限の検索：API ドキュメントに従い、ユーザー詳細の呼び出しには「メンバー情報読み取り権限」が必要です。
権限の追加：開発者バックエンドにアクセスし、作成済みのアプリを見つけてアプリ詳細に入り、権限管理 で「メンバー情報読み取り権限」を検索し、今すぐ申請 をクリックします。

ステップ 3：アクセストークンを取得する

アクセストークン を取得する前に、API で申請が必要なのが通常権限か機微権限かを確認してください。両者で取得方法が異なります。

通常権限 API

API を呼び出してトークンを取得する

社内アプリの accessToken を取得の API にアクセスし、右側の API デバッグ ボタンからサーバーサイドデバッグツールを開きます。
デバッグツールで、appkey（事前に取得した Client ID に置換） と appSecret（事前に取得した Client Secret に置換） の値を置換し、デバッグ開始 ボタンをクリックします。

重要

サーバーサイドデバッグコンソールはログイン状態でのみ利用可能で、対応するアプリにバインドする必要があります。下記コードをコピーし、cURL コマンドを使用して appkey（事前に取得した Client ID に置換） と appSecret（事前に取得した Client Secret に置換） の値を置換した後、直接呼び出すこともできます。例：

curl -X POST 'https://api.dingtalk.io/v1.0/oauth2/accessToken' \
  -H 'Content-Type: application/json' \
  -d '{
    "appKey": "事前に取得した Client ID に置換",
    "appSecret": "事前に取得した Client Secret に置換"
  }'

レスポンスの解析

API 呼び出しに成功すると、アクセストークンの値が生成されます。例：

{
  "accessToken" : "fw8ef8we8f76e6f7s8dxxxx", # コア認証情報
  "expireIn" : 7200 # 有効期間（2時間）
}

キャッシュと更新

access_token をデータベースまたはメモリにキャッシュし、定期的な更新（有効期限の 10 分前）を設定することを推奨します。
トークン取得 API を頻繁に呼び出すと、レート制限がトリガーされる可能性があるため避けてください。

機微権限 API

サードパーティアプリが組織を跨いだデータ連携と機能呼び出しを実現するには、厳格な権限付与フローを経る必要があります。組織による権限付与と個人による権限付与の 2 つのメカニズムを通じて、対象企業の利用許可とユーザーデータへのアクセス権限を取得します。

API 権限の申請

アプリで機微権限を使用するドキュメントの内容に従って、API 呼び出し権限を申請します。

権限付与スイートの導入

機微権限を申請後、権限付与スイートを導入する必要があります。ユーザーが権限付与ダイアログで承認すると authCode が返され、その後ユーザートークンの取得 API を呼び出して、ユーザーレベルの access_token と引き換えます。

ステップ 4：ユーザー詳細 API を呼び出す

通常権限 API

ユーザー詳細を取得するには、ユーザー詳細のクエリ API を呼び出す必要があります。取得方法は DingTalk SDK を直接使用する方法と、HTTP で直接取得する方法があります。実際のニーズに応じて選択してください。

方式 1：DingTalk SDK を使用する（推奨）

DingTalk SDK を使用して呼び出す場合、事前にサーバー API の差異を理解し、対応するバージョンの SDK をダウンロードする必要があります。詳細はサーバー API 差異詳解のドキュメントを参照してください。

SDK をインストール（Python の例）
pip install dingtalk-sdk

コード例

# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiV2UserGetRequest("https://api.dingtalk.io/topapi/v2/user/get")

req.userid="zhangsan"  # 実際のユーザー ID に置換
req.language="zh_CN"
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)

方式 2：HTTP リクエストを直接発行する

curl -i 'https://api.dingtalk.io/topapi/v2/user/get' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -d '{"userid":"実際のユーザー ID に置換","language":"zh_CN"}'

成功レスポンス

API の戻り値で "errcode":"0" かつ "errmsg":"ok" の場合、API 呼び出しに成功しています。

{
        "errcode":"0",
        "result":{
                "extension":"{\"趣味\":\"旅行\",\"年齢\":\"24\"}",
                "unionid":"z21HjQliSzpw0YWxxxxx",
                "boss":"true",
                "role_list":{
                        "group_name":"役職",
                        "name":"ディレクター",
                        "id":"100"
                },
                "exclusive_account":false,
                "manager_userid":"manager240",
                "admin":"true",
                "remark":"備考備考",
                "title":"技術ディレクター",
                "hired_date":"1597573616828",
                "userid":"zhangsan",
                "work_place":"フューチャーpark",
                "dept_order_list":{
                        "dept_id":"2",
                        "order":"1"
                },
                "real_authed":"true",
                "dept_id_list":"[2,3,4]",
                "job_number":"4",
                "email":"test@xxx.com",
                "leader_in_dept":{
                        "leader":"true",
                        "dept_id":"2"
                },
                "mobile":"13800138000",
                "active":"true",
                "org_email":"test@xxx.com",
                "telephone":"010-86123456-2345",
                "avatar":"xxx",
                "hide_mobile":"false",
                "senior":"true",
                "name":"山田太郎",
                "union_emp_ext":{
                        "union_emp_map_list":{
                                "userid":"5000",
                                "corp_id":"dingxxx"
                        },
                        "userid":"500",
                        "corp_id":"dingxxx"
                },
                "state_code":"86"
        },
        "errmsg":"ok"
}

エラーハンドリング

権限不足：「メンバー情報読み取り権限」が申請済みかを確認してください。
ユーザーが存在しない：userid が有効でスペルミスがないかを確認してください。
トークンの有効期限切れ：access_token を更新してから再試行し、access_token が有効でスペルミスがないかを確認してください。

機微権限 API

authCode でユーザーレベルの access_token と引き換えた後、ユーザー連絡先のプロフィール取得を呼び出して、ユーザーの名前、unionId などの情報を取得します。 API が 200 を返した場合、API は正常に実行されています。返却結果は以下の通りです：

{
  "nick" : "zhangsan",
  "avatarUrl" : "https://xxx",
  "mobile" : "150xxxx9144",
  "openId" : "123",
  "unionId" : "z21HjQliSzpw0Yxxxx",
  "email" : "zhangsan@example.com",
  "stateCode" : "86"
}

API 呼び出しガイド

認証と認可

連絡先

カレンダー

会議

AI Table

Docs とファイル

IM

事前準備

ステップ 1：DingTalk アプリを作成する

説明

説明

ステップ 2：権限を設定する

ステップ 3：アクセストークンを取得する

通常権限 API

API を呼び出してトークンを取得する

重要

レスポンスの解析

キャッシュと更新

機微権限 API

API 権限の申請

権限付与スイートの導入

ステップ 4：ユーザー詳細 API を呼び出す

通常権限 API

方式 1：DingTalk SDK を使用する（推奨）

方式 2：HTTP リクエストを直接発行する

成功レスポンス

エラーハンドリング

機微権限 API

​事前準備

​ステップ 1：DingTalk アプリを作成する

​説明

​説明

​ステップ 2：権限を設定する

​ステップ 3：アクセストークンを取得する

​通常権限 API

​API を呼び出してトークンを取得する

​重要

​レスポンスの解析

​キャッシュと更新

​機微権限 API

​API 権限の申請

​権限付与スイートの導入

​ステップ 4：ユーザー詳細 API を呼び出す

​通常権限 API

​方式 1：DingTalk SDK を使用する（推奨）

​方式 2：HTTP リクエストを直接発行する

​成功レスポンス

​エラーハンドリング

​機微権限 API

事前準備

ステップ 1：DingTalk アプリを作成する

説明

説明

ステップ 2：権限を設定する

ステップ 3：アクセストークンを取得する

通常権限 API

API を呼び出してトークンを取得する

重要

レスポンスの解析

キャッシュと更新

機微権限 API

API 権限の申請

権限付与スイートの導入

ステップ 4：ユーザー詳細 API を呼び出す

通常権限 API

方式 1：DingTalk SDK を使用する（推奨）

方式 2：HTTP リクエストを直接発行する

成功レスポンス

エラーハンドリング

機微権限 API