> ## 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.

# ベーシック概念

> DingTalk開発に必須のCorpIdやUserIdなどID体系と認証権限の基本を確認できます

本ドキュメントは DingTalk オープンプラットフォームの**開発ベーシック概念**ガイドであり、主に DingTalk 開発を初めて利用する開発者を対象として、コア用語、ID 体系、権限体系の理解を支援することを目的としています。

## 主要な開発バックエンド

本ドキュメントでは、開発者がロールに応じて使い分けるべき 3 つの主要な操作プラットフォームを明示しています。

### 開発者バックエンド

[DingTalk 開発者バックエンド](https://open-dev.dingtalk.io/#/index)は、アプリ開発を管理するためのサービスプラットフォームです。開発者はアプリ情報の設定やアプリの稼働状況の確認などを行えます。

<Warning>
  組織管理者、および**開発者権限**と**ワークベンチ管理**権限が付与されたサブ管理者のみが開発者バックエンドにアクセスできます。サブ管理者権限は [DingTalk 管理者バックエンド](https://oa.dingtalk.io/) で設定できます。
</Warning>

### 管理者バックエンド

[DingTalk 管理者バックエンド](https://oa.dingtalk.io/)は、組織管理者が組織構成、ユーザー権限、ワークベンチ設定を管理するためのコアプラットフォームです。このバックエンドを通じて、管理者は連絡先のインポート、承認フローの設定、サブ管理者への権限付与などの操作を行えます。

## コアな ID 体系

DingTalk 開発において、「誰か」と「どのアプリか」を区別することは非常に重要です。本ドキュメントでは以下の主要な ID を定義しています。

### CorpId

DingTalk における企業組織の一意の識別子を表します。ほとんどの企業向け API を呼び出す際には、必ずこの ID を用いて認証する必要があります。

**確認パス**：[DingTalk 開発者バックエンド](http://open-dev.dingtalk.io/)にログインし、**ホーム**で企業の `CorpId` を確認します。

### UserId

社内の具体的な社員の一意の識別子を表します。チャット送信、プロファイル照会、承認などの API で使用され、変更できません。

**確認パス**：[DingTalk 管理者バックエンド](http://oa.dingtalk.io/)にログインし、**連絡先 > メンバー管理**ページで社員の名前をクリックすると、社員の `UserId` を確認できます。

### UnionId

ユーザーのアプリ横断統一識別子です。同一ユーザーは同一のオープンプラットフォームアカウント配下のすべてのアプリで同じ UnionId を持ち、アプリ間でのデータ連携に使用されます。

**確認パス**：ユーザーの userId を用いて[ユーザー詳細の照会](/ja/open/development/query-user-details) API を呼び出し、`unionid` パラメータの値を取得します。

### Unified App ID

DingTalk がすべての種類のアプリに割り当てるグローバル一意の ID で、システム間連携の簡素化を目的とし、従来の AgentId/AppId 体系を段階的に置き換えるものです。

**確認パス**：[DingTalk 開発者バックエンド](http://open-dev.dingtalk.io/)にログインし、アプリ詳細に入った後、**認証情報とベーシック情報**で確認します。

### AgentId

社内アプリ（H5、ミニプログラムなど）の機能識別子です。主にワークベンチ管理 API（ホーム設定など）で使用されます。

**確認パス**：

* 社内アプリのウェブアプリ AgentId

* 社内アプリのミニプログラム AgentId

## 安全な認証情報と権限（Auth 体系）

この部分は開発において最もミスが起きやすい箇所で、API 呼び出しの認証およびサイレントログインのロジックに関わります。

### Client ID/Client Secret

* **定義**：アプリの認証情報のペア（ユーザー名とパスワードに類似）。
* **用途**：`access_token` を取得するために使用され、社内アプリとサードパーティアプリの両方でこの仕組みを使用します。
* **注意**：`Client Secret` は秘密鍵であるため、適切に保管し、漏洩させてはいけません。
* **取得方法**：[DingTalk 開発者バックエンド](http://open-dev.dingtalk.io/)で社内アプリまたはサードパーティ社内アプリを作成すると、システムが自動的に Client ID と Client Secret のペアを生成します。

### 説明

社内アプリをサービスプロバイダーに開発委託する場合、サービスプロバイダーは **CustomKey** と **CustomSecret** に基づいて権限付与を取得する必要があります。

### access\_token

* **定義**：OpenAPI を呼び出すための「チケット」。
* **用途**：保護された API を呼び出すたびに、正当性を検証するためにこの認証情報を持参する必要があります。
* **注意**：有効期間は通常 7200 秒（2 時間）で、有効期間内に繰り返し取得すると自動的に延長されます。
* **取得方法**：

  * 社内アプリの場合、[社内アプリのアクセストークンを取得する](/ja/open/development/obtain-the-access-token-of-an-internal-app) API を呼び出して access\_token を取得します。
  * サードパーティ社内アプリの場合、サードパーティアプリ認可企業のアクセストークンを取得する API を呼び出して access\_token を取得します。
* **差異**：

  * 社内アプリの `access_token` は、そのアプリが申請したすべての権限を持ちます。
  * サードパーティアプリの `access_token` の権限は、企業の認可範囲に制限されます。

### authCode

**定義**：ユーザー身元認証のための主要な認証情報。

**用途**：ユーザーの身元情報（`userid` など）と引き換えるために使用します。

**注意**：有効期間はわずか 5 分間で、一度使用すると失効し、再利用できません。

**取得方法**：getAuthCode、requestAuthCode などの API を呼び出して取得します。詳細な使い方は[本人認証（サイレントログイン）](/ja/open/development/sso-overview)を参照してください。

### jsapi\_ticket

**定義**：フロントエンドの JS API の署名を生成するために使用します。

**用途**：H5 マイクロアプリが DingTalk の提供する各種 JSAPI 機能（ユーザー情報の取得、チャットの開始、ネイティブコンポーネントの呼び出しなど）を安全に呼び出すために必要です。

**注意**：有効期間は 2 時間に設定されており、期限切れまたはパラメータの不一致により「jsapi ticket 読取失敗」や「署名検証失敗」などのエラーが発生します。

**取得方法**：`access_token` を使用して [jsapiTicket を取得する](/ja/open/development/create-a-jsapi-ticket) API を呼び出して取得します。

## クイックスタート

以下の擬似コードは、`CorpId` と `access_token` を使用して最もシンプルな API 呼び出しを行い、環境設定が正しいかを検証する方法を示しています。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET https://api.dingtalk.io/topapi/v2/user/get?access_token=ACCESS_TOKEN&userid=USERID
```

**手順説明**：

1. **認証情報の取得**：`Client ID` と `Client Secret` を使用して API を呼び出し、`access_token` を取得します。
2. **パラメータの準備**：管理者バックエンドで任意のメンバーの `UserId` を取得します。
3. **パラメータの置換**：上記のリクエストを構築し、`ACCESS_TOKEN` と `USERID` を置換します。
4. **テストの実行**：`"errcode": 0, "errmsg": "ok"` が返れば設定成功となり、その後の開発を続けられます。

> お知らせ：実際の開発では HTTPS を使用し、エラーハンドリングとリトライ機構を適切に実装してください。