開発ガイド概念の紹介
機密権限とは
DingTalkオープンプラットフォームでは、企業のコアデータや高リスクな操作に関わる一部の権限が「機密権限」として定義されています。アプリは個別に申請し、組織管理者の明示的な権限付与を受けて初めて、関連する OpenAPI を呼び出すことができます。 現在公開されている主な機密権限は以下のとおりです。指定されたロールを持つユーザーのみが、機密権限の付与または解除の操作を行うことができます。例えば、「全組織連絡先管理者」は
qyapi_manage_addresslist 権限を付与できる唯一のロールです。全組織連絡先管理者とは
qyapi_manage_addresslist は、連絡先書き込み系 API を呼び出すための機密権限スコープであり、その権限付与操作は「全組織連絡先管理者」に限定されます。
このロールは、以下の 2 つの条件を同時に満たす必要があります。
- 連絡先のベーシック管理権限を持つこと
- 管理範囲が全組織であること
統一権限付与スイートと authCode の説明
- 統一権限付与スイート：DingTalkが提供する標準化された組織レベルの権限付与ソリューションであり、サードパーティアプリがクライアント組織に機密権限をリクエストするシナリオに適用されます。本スイートを統合することで、開発者は権限を付与する組織を権限付与フローに誘導し、一時的な認可コード（authCode）を取得できます。
- authCode：一時的な認可コードであり、ユーザーが権限付与を確認した後に DingTalkから返されます。有効期間は短く設定されています。開発者はこのコードを使用して API を呼び出し
access_tokenと引き換え、保護された OpenAPI を呼び出す必要があります。
開発者の体験
アプリ開発時の権限スコープの関連付け
本記事では、機密権限スコープ qyapi_manage_addresslist を例に説明します。
まず、開発者管理画面で機密権限スコープ qyapi_manage_addresslist をアプリに関連付ける必要があります。これにより、アプリは機密権限配下の OpenAPI を呼び出せるようになります —— ロールメンバーの管理範囲を設定します。
開発者管理画面に機密権限スコープ qyapi_manage_addresslist が表示されない場合は、テクニカルサポートに連絡し、業務上のニーズを説明してください。審査を通過後、プラットフォームが開発者組織に対して機密権限を公開します。
権限を申請した後、開発者はさらに DingTalk統一権限付与スイートを統合し、権限を付与する組織の管理者に通知して、権限付与組織の管理者に権限付与を行ってもらう必要があります。そうしないと、API 呼び出し時に 403 が表示されます。
アプリによる OpenAPI の呼び出し
access_token を使用して対象の OpenAPI（部門の作成、ユーザーの更新など）を呼び出します。HTTP 200 が返れば呼び出しに成功したことを示します。ここでの開発者体験は、通常の権限スコープを使用する場合と同じです。
組織管理者の体験
アプリの権限付与の有効化
- 通常の権限は、アプリの有効化時に管理者からアプリへ付与されます。
- 機密権限は、アプリの有効化に伴って有効になることはなく、該当するロールを持つ管理者がワークスペースに入って手動で権限付与を完了する必要があります。
OA管理画面で監査ログを確認する
組織の OA管理画面では、機密権限に対する組織の操作（「アプリへの権限取得の承認」および「アプリに付与した権限の送信取消」など）を確認できます。よくある質問
アプリが OpenAPI を呼び出した際に 403 が返された場合、どのように解決すればよいですか？
考えられる原因と解決策は以下のとおりです。 開発者管理画面で必要な API 権限が正しく申請されているかご確認ください。- まず、開発者管理画面で API 権限が申請されているかを確認します。
-
組織側の権限付与が完了しているかを確認します:
- 権限付与組織の管理者をワークスペースに誘導し、手動での権限付与を完了させます。
- もしくは、統一権限付与スイート SDK を統合し、自動化された権限付与フローを実現します。