> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# API 呼び出し手順の詳細
> DingTalkオープンプラットフォームでアプリを新規登録し権限を設定してからAPIでユーザー詳細情報を取得します
本ガイドは、開発者がゼロから DingTalk オープンプラットフォームの API を呼び出し、アプリの新規登録から API の疎通までの全プロセスを完了できるよう支援することを目的としています。主要な手順、コード例、注意事項、デバッグ方法を網羅し、開発者がクイックスタートで API を呼び出せるようサポートします。
本例では社内アプリをベースに、API を呼び出して連絡先内のユーザーの詳細情報を取得する流れを説明します。他のアプリタイプの場合も、本ドキュメントを参考にできます。
## 事前準備
1. **ベーシック概念**：DingTalk オープンプラットフォームのベーシック概念および各製品ブロックのドキュメント説明を理解していること。詳細はベーシック概念のドキュメントを参照してください。
2. **API レート制限**：API のレート制限を理解していること。詳細は呼び出し回数とレート制限のドキュメントを参照してください。
3. **開発者権限**：[開発者バックエンド](https://open-dev.dingtalk.io/?spm=dd_developers.header.unLogin.openDevBtn\&hash=%23%2F#/) のサブ管理者および開発者権限を有していること。または、DingTalk 開発者にログインして新規ユーザーの新規登録とアクティベーションを完了することも可能です。
4. **ユーザー** `UserId` の取得：[DingTalk 管理バックエンド](http://oa.dingtalk.io/) にログインし、**連絡先 > メンバー管理** で `UserId` を確認します。詳細はベーシック概念の説明を参照してください。
## ステップ 1：DingTalk アプリを作成する
1. [開発者バックエンド](https://open-dev.dingtalk.io/?spm=dd_developers.header.unLogin.openDevBtn\&hash=%23%2F#/) にアクセスし、**アプリ開発** > **DingTalk アプリ** > **アプリの作成** をクリックします。
### 説明
2. アプリ情報を入力し、**保存** をクリックします。
| **設定項目** | **必須** | **設定の説明** |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| **アプリ名** | はい | アプリ名を入力します。アプリ名の最小文字数は 2 文字です。 |
| **アプリの説明** | はい | アプリが提供する製品またはサービスを簡潔に記述します。説明の最小文字数は 4 文字です。 |
| **アプリアイコン** | いいえ | アプリアイコンをアップロードします。アイコンは JPG/PNG 形式、240 px \* 240 px 以上、1:1 の比率、2 MB 以内、角丸なしのものを使用してください。 |
3. アプリ詳細ページに進み、**ベーシック情報** > **認証情報とベーシック情報** で、アプリ認証情報とベーシック情報を確認します。
4. アプリの **Client ID** と **Client Secret** を保存し、後続の API 呼び出しで使用します。
### 説明
**Client ID** と **Client Secret** の取得方法はベーシック概念の説明を参照してください。取得後は厳重に保管し、漏洩を防いでください。
## ステップ 2：権限を設定する
1. **必要な権限の検索**：API ドキュメントに従い、ユーザー詳細の呼び出しには「メンバー情報読み取り権限」が必要です。
2. **権限の追加**：[開発者バックエンド](https://open-dev.dingtalk.io/?spm=dd_developers.header.unLogin.openDevBtn\&hash=%23%2F#/) にアクセスし、作成済みのアプリを見つけてアプリ詳細に入り、**権限管理** で「メンバー情報読み取り権限」を検索し、**今すぐ申請** をクリックします。
## ステップ 3：アクセストークンを取得する
**アクセストークン** を取得する前に、API で申請が必要なのが [通常権限](/ja/open/development/add-api-permission) か [機微権限](/ja/open/development/use-sensitive-permissions) かを確認してください。両者で取得方法が異なります。
### 通常権限 API
#### API を呼び出してトークンを取得する
1. [社内アプリの accessToken を取得](/ja/open/development/obtain-the-access-token-of-an-internal-app) の API にアクセスし、右側の **API デバッグ** ボタンから [サーバーサイドデバッグツール](https://open.dingtalk.com/document/download/api-explorer) を開きます。
2. デバッグツールで、`appkey（事前に取得した Client ID に置換）` と `appSecret（事前に取得した Client Secret に置換）` の値を置換し、**デバッグ開始** ボタンをクリックします。
### 重要
サーバーサイドデバッグコンソールはログイン状態でのみ利用可能で、対応するアプリにバインドする必要があります。
下記コードをコピーし、cURL コマンドを使用して `appkey（事前に取得した Client ID に置換）` と `appSecret（事前に取得した Client Secret に置換）` の値を置換した後、直接呼び出すこともできます。例：
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.dingtalk.io/v1.0/oauth2/accessToken' \
-H 'Content-Type: application/json' \
-d '{
"appKey": "事前に取得した Client ID に置換",
"appSecret": "事前に取得した Client Secret に置換"
}'
```
#### レスポンスの解析
API 呼び出しに成功すると、アクセストークンの値が生成されます。例：
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"accessToken" : "fw8ef8we8f76e6f7s8dxxxx", # コア認証情報
"expireIn" : 7200 # 有効期間（2時間）
}
```
#### キャッシュと更新
* `access_token` をデータベースまたはメモリにキャッシュし、定期的な更新（有効期限の 10 分前）を設定することを推奨します。
* トークン取得 API を頻繁に呼び出すと、レート制限がトリガーされる可能性があるため避けてください。
### 機微権限 API
サードパーティアプリが組織を跨いだデータ連携と機能呼び出しを実現するには、厳格な権限付与フローを経る必要があります。組織による権限付与と個人による権限付与の 2 つのメカニズムを通じて、対象企業の利用許可とユーザーデータへのアクセス権限を取得します。
#### API 権限の申請
[アプリで機微権限を使用する](/ja/open/development/use-sensitive-permissions) ドキュメントの内容に従って、API 呼び出し権限を申請します。
#### 権限付与スイートの導入
機微権限を申請後、権限付与スイートを導入する必要があります。ユーザーが権限付与ダイアログで承認すると `authCode` が返され、その後 [ユーザートークンの取得](/ja/open/development/obtain-user-token) API を呼び出して、ユーザーレベルの `access_token` と引き換えます。
## ステップ 4：ユーザー詳細 API を呼び出す
### 通常権限 API
ユーザー詳細を取得するには、[ユーザー詳細のクエリ](/ja/open/development/query-user-details) API を呼び出す必要があります。取得方法は DingTalk SDK を直接使用する方法と、HTTP で直接取得する方法があります。実際のニーズに応じて選択してください。
#### 方式 1：DingTalk SDK を使用する（推奨）
DingTalk SDK を使用して呼び出す場合、事前にサーバー API の差異を理解し、対応するバージョンの SDK をダウンロードする必要があります。詳細はサーバー API 差異詳解のドキュメントを参照してください。
1. SDK をインストール（Python の例）
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install dingtalk-sdk
```
2. コード例
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# -*- 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 リクエストを直接発行する
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 呼び出しに成功しています。
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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` と引き換えた後、[ユーザー連絡先のプロフィール取得](/ja/open/development/dingtalk-retrieve-user-information) を呼び出して、ユーザーの名前、unionId などの情報を取得します。
API が 200 を返した場合、API は正常に実行されています。返却結果は以下の通りです：
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"nick" : "zhangsan",
"avatarUrl" : "https://xxx",
"mobile" : "150xxxx9144",
"openId" : "123",
"unionId" : "z21HjQliSzpw0Yxxxx",
"email" : "zhangsan@example.com",
"stateCode" : "86"
}
```