Postmanを使ってMicrosoft Dataverse Web APIで部署を追加

はじめに

前回（「【MSAL】Dataverse Web API で追加・更新・削除・画像アップロード・画像ダウンロード」）では、JavaScript によるトークン取得、Microsoft Dataverse Web API へのリクエストをやりましたが、今回、Postman を Windows10 にインストールして、ノーコーディングで、API リクエストを行いました。
Postman にて、前回と同じことが可能なのですが、今回は、Postman インストール～部署作成、削除までをゴールとします。

PostmanでAPIリクエストする人は、部署 作成権限のある管理者とします。

【 部署 】

ここで言う "部署" は、Dynamics 365(Dynamics CRM) の部署で、Dataverse の 部署 テーブル（ businessunit テーブル）のレコードの事です。

【 Postman 】

Postmanは、開発者がAPIを設計、構築、テスト、反復するためのAPIプラットフォームです。

【 検証環境 】

Windows 10 Pro x64

Postman for Windows Version 10.0.35

他、Dataverse等の状況は、2022年10月現在の状況を元にしています。

Postman インストール

https://www.postman.com/downloads/ から Postman をダウンロードします。

Postman-win64-Setup.exe を起動して、インストールします。

Create Free Account にて、アカウントを作成します。

以降、アカウント作成のところは、省略し、サインインしたところからとします。

Azure AD アプリの登録

Postman の作業の前に、

Azure Active Directory → アプリの登録 → ＋ 新規登録 をクリックします。

名前：Postman Dataverse（任意）
サポートされているアカウントの種類：この組織ディレクトリのみに含まれるアカウント (<テナント名> のみ - シングル テナント)
リダイレクト URI (省略可能)：パブリック クライアント/ネイティブ (モバイルとデスクトップ) https://oauth.pstmn.io/v1/callback
とします。

アプリケーション (クライアント) ID、ディレクトリ (テナント) ID をメモします。後で、Postman の準備をするときに必要になります。

API のアクセス許可、アクセス許可の追加 をクリックします。

Dynamics CRM をクリックします。

アクセス許可 のところの user_impersonation にチェックを入れて、アクセス許可の追加 をクリックします。

ここまでで、Azure 側の作業は終わりです。

証明書とシークレット → クライアントシークレット を使って、人の代わりにアプリケーションの権限で API 実行できますが、今回は、管理者がサインインを行います。

Postman 準備

Workspaces → Create Workspace をクリックし、Test Workspace を作成します。

My Workspace でも良いですが、ここでは、専用のWorkspaceで作業していくものとします。

Create Collection をクリックし、New Collection を作成します。

New Collection は任意の名称に変えられますが、そのままとします。

【 Workspaces 】

Collection の集まりをまとめる箱のようなものです。

【 Collection 】

APIリクエスト（URL、パラメータ）のひな形集のようなものです。

Authorization タブ、Type のところを OAuth 2.0 とします。

Authorization タブ、Configure New Token （下の方）のところを以下のように入力します。

Token Name：Postman Dataverse（任意）
Grant Type：Authorization Code (With PKCE)
Callback URL：https://oauth.pstmn.io/v1/callback
Auth URL：https://login.microsoftonline.com/0c6c0***-****-****-****-*******d0d2b/oauth2/v2.0/authorize
Access Token URL：https://login.microsoftonline.com/0c6c0***-****-****-****-*******d0d2b/oauth2/v2.0/token
Client ID：3b43e***-****-****-****-*******914d8
Scope：https://***********.api.crm*.dynamics.com/.default

この記事を書いていたときは必要なかったのですが、2022年12月に Postman v10.6.7 にアップデートされて、Client Authentication のところを Send client credentials in body にする手順が必要になりました。

0c6c0***-****-****-****-*******d0d2b のところは、Azure Active Directory アプリの登録でメモした ディレクトリ (テナント) ID です。
Client ID の入力値は、Azure Active Directory アプリの登録でメモした アプリケーション (クライアント) ID です。
Scope の https://***********.api.crm*.dynamics.com/ 部分は、
[Organization URI] です。
Power Apps 右上の歯車 → 開発者リソース → Web API エンドポイント に表示される URL です。

Client ID 等は、環境変数に登録して、{{clientid}} のように変数で書くのが推奨されますが、今回は、直書きです。

Get New Access Token をクリックします。

サインインします。

承諾 をクリックします。（初めてサインインしたときだけアクセス許可を聞かれます。）

Proceed をクリックします。

Use Token をクリックします。

トークンが入力されていると準備完了です。

Save をクリックして、Collection を保存します。

保存し忘れると、この後の GET でこのトークンの設定が引き継がれず、401 エラーが返ります。

Save は、画面が十分に広い場合、アイコンで表示されます。

GET 動作確認

動作確認として、とりあえず、取引先企業 テーブル（ account テーブル）の内容を API で GET してみることにします。

Add a request をクリックします。

GET：https://***********.api.crm*.dynamics.com/api/data/v9.2/accounts
とします。

https://***********.api.crm*.dynamics.com/ 部分は、先ほど説明があった [Organization URI] です。
accounts は、テーブル名 account の複数形です。このケースに限らず、テーブル名は常に複数形で書かないとエラーになります。

リクエストの名前を設定できますが、とりあえず、New Request のままで進めています。

Send をクリックします。

ＯＫ！

POST 部署作成

部署を作成します。
部署を作成するときは、必ず、親部署の指定が必要です。
必ず、ルート部署が１つ有り、今回、これを親部署とします。ルート部署と同格の部署は作成できません。

まず、 GET：https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits
で 部署 テーブル（ businessunit テーブル）の内容を出力し、ルート部署の businessunitid を確認しておきます。（Power Apps - Dataverse 画面でも確認できます。）

判明した businessunitid は、
b982d***-****-****-****-*******27069 とします。

Body タブをクリックして、raw ラジオボタンをクリック、JSON を選択します。

POST：https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits
に変更して、 下記内容を入力します。

{
  "parentbusinessunitid@odata.bind": "/businessunits(b982d***-****-****-****-*******27069)",
  "name": "NewBU"
}

Send ボタンをクリックして、204 No Content が返れば、成功です。

Power Apps - Dataverse → テーブル → 部署 を確認すると、追加されています。

ＯＫ！！

DELETE 部署削除

先ほど作成した部署を削除します。
部署を削除するときは、事前に isdisabled を true にする必要があります。

まず、
GET：https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits
で 部署 テーブル（ businessunit テーブル）の内容を出力し、先ほど作成した部署 "NewBU" の businessunitid を確認しておきます。（Power Apps - Dataverse 画面でも確認できます。）

判明した businessunitid は、
654b8***-****-****-****-*******279c8 とします。

PATCH：https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits(654b8***-****-****-****-*******279c8)
に変更して、 Body タブ入力欄に下記内容を入力します。

{
  "isdisabled": true
}

Send ボタンをクリックして、204 No Content が返れば、成功です。

Power Apps - Dataverse → テーブル → 部署 → NewBU を確認すると、無効にする 列（ isdisabled 列）が "はい" になっています。

DELETE：https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits(654b8***-****-****-****-*******279c8)
に変更して、Send ボタンをクリックします。

204 No Content が返れば、成功です。
Power Apps - Dataverse → テーブル → 部署 から NewBU が消えているはずです。

Voila!

トラブルシューティング

現象：トークンが取得できない。

エラー：Authentication failed
Couldn’t complete authentication. Check the Postman Console for more details.

Postman Console：Error: [object Object]

【 Postman Console 】

Ctrl+Alt+C で開きます。macOSの場合は、⌘+Option+C です。

原因：Grant Type が間違っている。（Implicitになっていたり。）

現象：トークンが取得できない。

エラー：Authentication failed
Couldn’t complete authentication. Check the Postman Console for more details.

Postman Console：Error: AADSTS9002327: Tokens issued for the 'Single-Page Application' client-type may only be redeemed via cross-origin requests.
あるいは、
Error: AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.

原因：Azure Active Directory アプリの登録の手順で、パブリック クライアント/ネイティブ (モバイルとデスクトップ) 以外の Web や シングルページアプリケーション などを選択している。

現象：トークンが取得できない。（サインイン中に問題が発生）

エラー：申し訳ありませんが、サインイン中に問題が発生しました。
AADSTS50011: The redirect URI 'https://oauth.pstmn.io/v1/callback' specified in the request does not match the redirect URIs configured for the application '3b43e***-****-****-****-*******914d8'. Make sure the redirect URI sent in the request matches one added to your application in the Azure portal. Navigate to https://aka.ms/redirectUriMismatchError to learn more about how to fix this.

原因：リダイレクト URI（Azure AD - アプリの登録 - 認証）が間違っている。

現象：GET https://***********.api.crm*.dynamics.com/api/data/v9.2/account で 404 Not Found

エラー："code": "0x8006088a",
"message": "Resource not found for the segment 'account'."

原因：テーブル名を複数形にしていない。
誤：account
正：accounts

現象：POST https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits で 415 Unsupported Media Type

エラー："code": "0x8006088a",
"message": "POST request requires Content-Type application/json."

原因：JSON を選択していない。

現象：POST https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits で 400 Bad Request

エラー："code": "0x80041d35",
"message": "Only one organization and one root business are allowed."

原因：親部署を指定していない。

現象：POST https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits で 400 Bad Request

エラー："code": "0x0",
"message": "Error identified in Payload provided by the user for Entity :'businessunits', For more information on this error please follow this help link https://go.microsoft.com/fwlink/?linkid=2195293 ----> InnerException : Microsoft.OData.ODataException: A 'PrimitiveValue' node with non-null value was found when trying to read the value of the property 'parentbusinessunitid'; however, a 'StartArray' node, a 'StartObject' node, or a 'PrimitiveValue' node with null value was expected.

原因：親部署の指定の仕方が間違っている。
誤："parentbusinessunitid": "b982d***-****-****-****-*******27069",
正："parentbusinessunitid@odata.bind": "/businessunits(b982d***-****-****-****-*******27069)",

現象：POST https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits で 404 Not Found

エラー："code": "0x80040217",
"message": "BusinessUnit With Id = b982d***---****-*******270aa Does Not Exist"

原因：親部署の ID が間違っている。

現象：DELETE https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits(654b8***-****-****-****-*******279c8) で 400 Bad Request

エラー："code": "0x80041d60",
"message": "Not disabled business unit cannot be deleted."

原因：削除しようとしている部署の isdisabled 列 が false になっている。

現象：DELETE https://***********.api.crm*.dynamics.com/api/data/v9.2/businessunits(654b8***-****-****-****-*******279c8) で 400 Bad Request

エラー："code": "0x80041d61",
"message": "Business unit has a child business unit and cannot be deleted."

原因：子部署があるため、削除できない。（末端から削除が必要）

現象：401 Unauthorized

原因：トークンの時間切れの可能性があります。（Get New Access Token ボタンで取得しなおせば、ＯＫ）

https://learn.microsoft.com/ja-jp/power-apps/developer/data-platform/authenticate-oauthに「token が 1 時間以内に期限切れになる」という記述があります。