API 呼び出し説明
本 API を呼び出すと、一般アカウントユーザーの詳細または企業アカウントユーザーの詳細を照会できます。呼び出し時のパラメータ使用に多くの違いがあるため、開発者が確認しやすいよう、新しいユーザーのアカウントタイプ別に分けて最適化しています。- 一般アカウントユーザー詳細の照会については、本ドキュメントを参照してください。
- 企業アカウントユーザー詳細の照会については、企業アカウントユーザー詳細を照会を参照してください。
- 社内アプリでユーザーの電話番号やメール情報を取得するには、連絡先の電話番号およびメール取得権限を追加する必要があります。追加方法は以下のとおりです。 DingTalk 開発者管理画面にログイン > 社内開発 > 権限を追加するアプリを選択 > 権限管理 > 連絡先管理ページで、企業社員の電話番号情報とメールなどのプロフィールにチェックを入れ、権限をリクエストをクリックします。
- サードパーティ社内アプリでユーザーの電話番号やメール情報を取得する場合は、DingTalk 統合認証スイートを使用して取得できます。
リクエスト
| 基本情報 | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/v2/user/get |
| HTTP Method | POST |
| サポートされるアプリタイプ | appType-社内アプリ appType-サードパーティ社内アプリ |
| 必要な権限 | permission-qyapi_get_member-ユーザー情報読み取り権限 |
クエリパラメータ
| 名前 | タイプ | 必須 | 例 | 説明 |
|---|---|---|---|---|
| access_token | String | はい | bE74xxxx | この API を呼び出すためのアプリ認証情報。 - 社内アプリの場合、社内アプリの access_token 取得 API で取得します。 - サードパーティ社内アプリの場合、サードパーティ企業の access_token 取得 API で取得します。 |
リクエストボディ
| 名前 | タイプ | 必須 | 例 | 説明 |
|---|---|---|---|---|
| userid | String | はい | manager4220 | ユーザーの userId。 |
| language | String | いいえ | zh_CN | 連絡先の言語。 - zh_CN:中国語(デフォルト) - en_US:英語 |
リクエスト例
curl -X POST "https://api.dingtalk.io/topapi/v2/user/get" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=b97a231d-7dd8-4243-ac4e-6b75b2a1e28a' \
-d 'language=zh_CN' \
-d 'userid=zhangsan'
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/get");
OapiV2UserGetRequest req = new OapiV2UserGetRequest();
req.setUserid("001");
req.setLanguage("zh_CN");
OapiV2UserGetResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiV2UserGetRequest("https://api.dingtalk.io/topapi/v2/user/get")
req.userid="zhangsan"
req.language="zh_CN"
try:
resp= req.getResponse(access_token)
print(resp)
except Exception,e:
print(e)
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');
$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiV2UserGetRequest;
$req->setUserid("zhangsan");
$req->setLanguage("zh_CN");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/user/get");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/get");
OapiV2UserGetRequest req = new OapiV2UserGetRequest();
req.Userid = "zhangsan";
req.Language = "zh_CN";
OapiV2UserGetResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
レスポンス
レスポンスボディ
| 名前 | タイプ | 例 | 説明 |
|---|---|---|---|
| request_id | String | 4e7exhl6pm0t | リクエスト ID。 |
| errcode | Number | 0 | リターンコード。 |
| errmsg | String | ok | リターンコードの説明。 |
| result | Object | 戻り結果。 | |
| userid | String | zhangsan | 社員の userId。 |
| unionid | String | z21HjQliSzpw0YWCNxmii6u2Os62cZ62iSZ | 当該開発者の企業アカウント範囲内における社員の一意識別子。 |
| name | String | 山田太郎 | 社員名。 |
| avatar | String | xxx | プロフィール写真。 説明 社員がデフォルトのプロフィール写真を使用している場合、このフィールドは返されません。手動で設定した場合のみ返されます。 |
| state_code | String | 86 | 国際電話の国番号。 説明 サードパーティ社内アプリではこのフィールドは返されません。state_code を取得する必要がある場合は、DingTalk 統合認証スイートを使用してください。 |
| manager_userid | String | user01 | 社員の直属の上司。 説明 社員の企業管理バックエンドのプロフィールパネルにある直属の上司に値がある場合のみ、このフィールドが返されます。 |
| mobile | String | 13800138000 | 電話番号。 説明 - 社内アプリの場合、連絡先の企業社員の電話番号情報権限が有効になっているアプリのみ、このフィールドが返されます。 - サードパーティ社内アプリではこのフィールドは返されません。mobile を取得する必要がある場合は、DingTalk 統合認証スイートを使用してください。 |
| hide_mobile | Boolean | false | 電話番号を非表示にするかどうか。 - true:非表示 - false:表示 説明 電話番号を非表示にすると、プロフィールページで電話番号が非表示になりますが、DING の送信や DingTalk 無料ビジネスコールの発信は引き続き可能です。 |
| telephone | String | 010-86123456-2345 | 内線番号。 説明 サードパーティ社内アプリではこのパラメータは返されません。 |
| job_number | String | 4 | 社員番号。 |
| title | String | 技術ディレクター | 職位。 |
| String | test@xxx.com | 社員のメール。 説明 - 社内アプリの場合、連絡先のメールなどのプロフィール権限が有効になっているアプリのみ、このフィールドが返されます。 - サードパーティ社内アプリではこのパラメータは返されません。email を取得する必要がある場合は、DingTalk 統合認証スイートを使用してください。 | |
| work_place | String | 未来パーク | 勤務地。 説明 - 社員プロフィールパネルでこのフィールドに値がある場合のみ正常に返されます。値がない場合、このフィールドは返されません。 - 社内アプリの場合、連絡先のメールなどのプロフィール権限が有効になっているアプリのみ、このフィールドが返されます。 - サードパーティ社内アプリではこのパラメータは返されません。 |
| remark | String | 表示名表示名 | 表示名。 説明 - 社員プロフィールパネルでこのフィールドに値がある場合のみ正常に返されます。値がない場合、このフィールドは返されません。 - 社内アプリの場合、連絡先のメールなどのプロフィール権限が有効になっているアプリのみ、このフィールドが返されます。 - サードパーティ社内アプリではこのパラメータは返されません。 |
| exclusive_account | Boolean | false | 企業アカウントかどうか。 - true:はい - false:いいえ |
| org_email | String | test@xxx.com | 社員のエンタープライズメール。 社員のエンタープライズメールが有効でない場合、戻り情報にこのデータは含まれません。 説明 サードパーティ社内アプリではこのパラメータは返されません。 |
| dept_id_list | Number[] | [2,3,4] | 所属部門の id リスト。 |
| dept_order_list | Object[] | 対応する部門内における社員の並び順。 | |
| dept_id | Number | 2 | 部門 id。 |
| order | Number | 1 | 部門内における社員の並び順。 |
| extension | String | {"趣味":"旅行","年齢":"24"} | 拡張属性。最大長は 2000 文字。 説明 - 社員プロフィールパネルで追加された拡張フィールドに値がある場合のみ返されます。 - 社内アプリの場合、連絡先のメールなどのプロフィール権限が有効になっているアプリのみ、このフィールドが返されます。 - サードパーティ社内アプリではこのフィールドは返されません。 - 重要:新しい属性を直接追加すると元の属性値が上書きされます。既存の属性を取得してから新しい属性を既存の属性に追加し、全体を更新してください。 |
| hired_date | Number | 1597573616828 | 入社日。Unix タイムスタンプ、単位はミリ秒。 説明 - プロフィールパネルの入社日フィールドに値がある場合のみ返されます。 - サードパーティ社内アプリではこのパラメータは返されません。 |
| active | Boolean | true | DingTalk を有効化したかどうか。 - true:有効化済み - false:未有効化 |
| real_authed | Boolean | true | 実名認証が完了しているかどうか。 - true:認証済み - false:未認証 |
| senior | Boolean | true | 企業の上級幹部かどうか。 - true:はい - false:いいえ |
| admin | Boolean | true | 企業の管理者かどうか。 - true:はい - false:いいえ |
| boss | Boolean | true | 企業の代表者かどうか。 - true:はい - false:いいえ |
| leader_in_dept | Object[] | 社員所属部門情報およびリーダーかどうか。 - 社員所属部門の部門 ID。 - 対応する部門内で社員がリーダーかどうか。 - true:はい - false:いいえ | |
| dept_id | Number | 2 | 部門 ID。 |
| leader | Boolean | true | リーダーかどうか。 - true:はい - false:いいえ |
| role_list | Object[] | ロールリスト。 | |
| id | Number | 100 | ロール ID。 |
| name | String | ディレクター | ロール名。 |
| group_name | String | 職務 | ロールグループ名。 |
| union_emp_ext | Object | ユーザーが関連組織から来た場合の関連情報。 説明 ユーザーが所属する企業に関連関係を持つ企業がある場合、このフィールドが返されます。 | |
| userid | String | 500 | 社員 id の userId。 |
| union_emp_map_list | Object[] | 関連マッピング関係。 | |
| userid | String | 5000 | 関連ブランチ組織内の社員 userId。 |
| corp_id | String | dingxxx | 関連ブランチ組織の企業 corpId。 |
| corp_id | String | dingxxx | 現在のユーザーが所属する組織の企業 corpId。 |
| dept_position_list | DeptPosition[] | 部門内の職務情報。 | |
| extension_i18n | Json | {"趣味": {"zh_CN": "旅游", "en_US": "travel", "ja_JP": "旅行"}} | 拡張属性の国際化値。 |
レスポンスボディ例
{
"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":"未来パーク",
"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"
}
エラーコード
API 呼び出しでエラーが発生した場合は、エラーメッセージをもとにグローバルエラーコードドキュメントで解決方法を確認してください。| エラーコード(errcode) | エラーコード説明(errmsg) | 解決方法 |
|---|---|---|
| 33012 | 無効な userId | userId が正しいかご確認ください |
| 400002 | 無効なパラメータ | パラメータが要求どおり入力されているかご確認ください |
| -1 | システムビジー | 後でもう一度お試しください |