コルネの進捗や備忘録が記されたなにか

進捗や成果物や備忘録てきななにかを雑に更新していきます。

Dataverse Web APIを利用する

Dataverse Power Automate

スポンサードリンク

はじめに

Dataverse Web APIを利用するためのクイックスタートを覚書程度にまとめました。

最終的にPower AutomateのHTTPコネクタを利用してAPIを投げることができるようになるのがこの記事のゴールです。

参考文献

チュートリアル: アプリを Azure Active Directory に登録する
Microsoft Dataverse で OAuth 認証を使用する
Power Platform 管理センターでアプリケーション ユーザーを管理する
Web API を使用して演算を実行する

DataverseでOAut認証を行う

AADにアプリケーションを登録する

ここに従ってやります。

learn.microsoft.com

Azure portalにアクセスして、アプリケーションの登録を行います。

  • 名前
    アプリケーションの表示名を設定します。
  • サポートされているアカウントの種類
    APIを利用できる範囲を設定します。
    今回は「この組織ディレクトリのみに含まれるアカウント」を設定します。
  • リダイレクトURI
    ユーザ認証成功時のリダイレクトURIを設定します。
    この設定は省略可能で、後程変更も可能ではありますが、必要な項目なので設定しておきましょう。
    「Web」のほかに、「パブリック クライアント/ネイティブ」「SPA」があります。

作成が完了したら、概要ページが表示されるかと思いますので、「アプリケーションID」をコピーします。

続いて「マニフェスト」よりallowPublicClientをtrueに変更して「保存」します。

「APIのアクセス許可」より「アクセス許可の追加」を行います。

「所属する組織で使用しているAPI」より「Dataverse」を選択します。

「委任されたアクセス許可」を選択して、オプションにチェックを付けたら「アクセス許可の追加」を選択します。

余談ですが、ここで表示されているDynamics CRMのロゴとアイコンは将来的にDataverseに置き換えられるらしいですね。

これでAzure Active Directoryでのアプリケーション登録は完了です。

最後に、「証明書とシークレット」よりシークレットキーを作成しておきます。

Dataverseアプリケーションユーザの作成

Power Platform管理センターにアクセスして、対象の環境の「設定」を選択します。

「ユーザーとアクセス許可」より「アプリケーションユーザー」を選択します。

「新規アプリユーザー」より新規Dataverseアプリケーションユーザーを作成します。

「アプリの追加」より先ほど作成したアプリケーションを選択します。

部署(Business unitのこと)を選択後、セキュリティロールを選択して「作成」を行います。

これでDataverseでOAuth認証を行う準備ができました。

Dataverse Web APIを実行する

API実行に必要な情報

Organization URI

設定 > 開発者リソース の「Web API エンドポイント」より確認することが可能です。

/api/dataより前の箇所ですね。

各値の説明は以下ドキュメントにあります。

HTTP 要求の作成とエラーの処理 (Microsoft Dataverse) - Power Apps | Microsoft Learn

認証情報

AADに作成したアプリケーションより、「アプリケーションID」と「ディレクトリID」を控えます。

ディレクトリIDが、テナント(tenant)
アプリケーションIDが、クライアントID(clientId)
となります。

次に証明書もしくはシークレット情報を控えます。
クライアント シークレットを選んだ場合は、「値」を控えておきます。

Postman

PostmanからDataverse Web APIを実行してみます。

先ほどの情報を環境変数(Enviroments)に保存しておきます。

url = Organization URI
です。

他のシークレット値も自身の環境に合わせて設定してください。

残りの環境変数は以下となっています。

VARIABLE VALUE
version 9.2
webapiuri {{url}}/api/data/v{{version}}/
callback アプリ作成時に設定したリダイレクトURI
authurl https://login.microsoftonline.com/common/oauth2/authorize?resource={{url}}

続いて認証情報を設定します。

「Authorization」にて、「Type」は「OAuth 2.0」、「Add authorization data to」では「Request Headers」を選択します。

トークンの取得を行います。

以下のように設定を行います。

「Token Name」はトークン名の名前なので任意の名前でよいです。

入力が完了したらトークンの取得を行いますが、以下の注意に該当する場合は「Clear cookies」でCookieの消去を行っておきましょう。

「Get New Access Token」でアクセストークの取得を行います。
サインインダイアログ ボックスが表示されますので、 ユーザー名とパスワードを入力してサインインを行ってください。

...
恐らく以下のようなエラーが出たかと思います。

AADSTS700051: response_type 'token' is not enabled for the application.

これはAADで作成したアプリケーションでこの認証が許可されていないからですね。

AADのアプリケーションに戻り、「認証」で「アクセストークン」にチェックを入れてください。

この設定を行った後、再度アクセストークンの取得を行ってみてください。
今度は無事サインインが行われ、アクセストークンの取得ができたかと思います。

「Access Token」で作成したトークン名を選択し、トークンが設定されていることを確認してください。

設定ができたら、接続のテストをしてみましょう。

利用するのはWhoAmI Functionです。

以下を入力後「Send」を選択してAPIのテストをします。

GET {{webapiuri}}WhoAmI

Bodyにて以下のような応答が問題なく返ってきてくれればテストは成功です。

{
    "@odata.context": "https://[Organization URI]/api/data/v[Version]/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
    "BusinessUnitId": "[BusinessUnitId]",
    "UserId": "[UserId]",
    "OrganizationId": "[OrganizationId]"
}

続いて特定のテーブルから値を取得してみます。

今回取得するテーブルには以下のような情報が含まれています。

このテーブルから、Numberを昇順で並び変えて先頭5件のNumber, Text, Dateを表示させようと思います。

テーブル名、列名には論理名を設定するようにしてください。
上記のような条件を取得する際は以下のようになります。

GET {{webapiuri}}cr1f8_mysampledataverses?$select=cr1f8_number,cr1f8_text,cr1f8_date&$orderby=cr1f8_number asc&$top=5

Headersには以下を設定します。

Content-Type:application/json; charset=utf-8
OData-MaxVersion:4.0
OData-Version:4.0
Accept:application/json

APIを実行することで以下のような結果が得られます。

{
    "@odata.context": "[webapiuri]/$metadata#cr1f8_mysampledataverses(cr1f8_number,cr1f8_text,cr1f8_date)",
    "value": [
        {
            "@odata.etag": "W/\"3134549\"",
            "cr1f8_number": 0,
            "cr1f8_text": "a",
            "cr1f8_date": "2023-01-07T07:31:14Z",
            "cr1f8_mysampledataverseid": "60bdcf38-5d8e-ed11-81ad-002248e99e0c"
        },
        {
            "@odata.etag": "W/\"3134550\"",
            "cr1f8_number": 1,
            "cr1f8_text": "b",
            "cr1f8_date": "2023-01-08T07:31:14Z",
            "cr1f8_mysampledataverseid": "61bdcf38-5d8e-ed11-81ad-002248e99e0c"
        },
        {
            "@odata.etag": "W/\"3134551\"",
            "cr1f8_number": 2,
            "cr1f8_text": "c",
            "cr1f8_date": "2023-01-09T07:31:14Z",
            "cr1f8_mysampledataverseid": "62bdcf38-5d8e-ed11-81ad-002248e99e0c"
        },
        {
            "@odata.etag": "W/\"3134556\"",
            "cr1f8_number": 3,
            "cr1f8_text": "d",
            "cr1f8_date": "2023-01-10T07:31:14Z",
            "cr1f8_mysampledataverseid": "64bdcf38-5d8e-ed11-81ad-002248e99e0c"
        },
        {
            "@odata.etag": "W/\"3134552\"",
            "cr1f8_number": 4,
            "cr1f8_text": "e",
            "cr1f8_date": "2023-01-11T07:31:14Z",
            "cr1f8_mysampledataverseid": "63bdcf38-5d8e-ed11-81ad-002248e99e0c"
        }
    ]
}

以上、PostmanからのDataverse Web APIの実行でした。
その他のAPIについてはドキュメントをご確認ください。

Power Automate

以下変数を用意します。
(変数でも機密情報扱いにできたらよかったんですけどね。
機密扱いにしたいなら「作成」利用する必要があります。)

まずは先ほどと同じようにWhoAmI を実行してみましょう。

URI

@{variables('Organization URI')}/api/data/v9.2/WhoAmI

上記のように、「詳細オプション」を表示させて認証情報を入力することを忘れないでください。

Postmanのときと異なり、今回はAccess Tokenではなくシークレットで認証します。

対象ユーザー(audience)には、「Organization URI」と同様のものを設定します。

実行してみて問題なければ、続いて先ほど(Postman)同様テーブルから値を取得してみましょう。

先ほどと同様のAPIを実行します。

URI

@{variables('Organization URI')}/api/data/v9.2/cr1f8_mysampledataverses?$select=cr1f8_number,cr1f8_text,cr1f8_date&$orderby=cr1f8_number asc&$top=5

ヘッダー

{
    "Content-Type": "application/json; charset=utf-8",
    "OData-MaxVersion": "4.0",
    "OData-Version": "4.0",
    "Accept": "application/json"
}

設定に問題がなければ、先ほどPostmanで実行した結果と同じものを取得することができるはずです。

エラーが発生した場合は設定がどこか間違えている可能性が高いのでエラーメッセージなどからエラー原因を確認して修正しましょう。

おわりに

Dataverse Web APIの使用方法まとめてみました。

ドキュメント絶妙にわかりにくいですねw


スポンサードリンク