Customer Insights - Data API に関する作業
Dynamics 365 Customer Insights - Data は、Customer Insights のデータに基づいて独自のアプリケーションを構築するための API を提供します。 これらの API の詳細は、API リファレンス に一覧表示されます。 これらには、操作、パラメーター、および応答に関する追加情報が含まれています。
注意
Customer Insights - Data テーブルは、Dataverse API を使用してにアクセスすることもできます。 より広範なフィルター、より優れたスループット、短い待ち時間を提供するため、Dataverse API を使用して、Customer Insights データを照会することをお勧めします。 詳細については、Customer Insights 用 Dataverse API を参照してください。
API 試用に関する入門情報
管理者はデータへの API アクセスを有効にする必要があります。 アクセスが有効になると、すべてのユーザーがサブスクリプション キーで API を使用できるようになります。
Customer Insights - Data にサインインするか、または Customer Insights の試用版にサインアップします。
設定>アクセス許可 に移動して、API タブを選択します。
環境への API アクセスを設定していない場合は、有効化 を選択します。
API を有効にすると、API 要求で使用される環境に対してプライマリおよびセカンダリのサブスクリプション キーが作成されます。 キーを生成するには、プライマリの再生成 または API タブで セカンダリの再生成 を選択することでキーを再生成できます。
API の詳細を確認 を選択して、API を試してください。
API オペレーションを検索して選択し、それを試して みてください。
サイド ペインで、認証の値を、ドロップダウン メニューから暗黙的に許可に設定します。
Authorizationヘッダーはベアラー トークンで追加されます。 サブスクリプション キーは自動的に入力されます。必要に応じて、必要なすべてのクエリ パラメーターを追加します。
サイド ペインの下までスクロールして、送信 を選択します。
ペインの下部に HTTP 応答が表示されます。
Azure portal で新しいアプリの登録を作成する
新しい アプリ登録 を作成して、委任されたアクセス許可を使用して Azure アプリケーションで API を使用します。
はじめにセクション を完了させます。
Customer Insights データにアクセスできるアカウントで Azure portal にサインインします。
アプリ登録 を検索して選択します。
新規登録を選択して、アプリケーション名を入力し、アカウントの種類を選択します。
必要に応じて、リダイレクト URL を追加します。 ローカル コンピュータでアプリケーションを開発するには、http://localhost で十分です。
登録 を選択します。
新しいアプリの登録で、API アクセス許可 に移動します。
Add a permission を選択し、サイド ペインで Customer Insights 向けの Dynamics 365 AI を選択します。
アクセス許可の種類では、委任されたアクセス許可を選択し、user_impersonation のアクセス許可を選択します。
アクセス許可の追加 を選択します。
... に管理者の同意を付与する を選択して、アプリの登録を完了します。
ユーザーがログインせずに API にアクセスするには、サーバー間アプリケーションのアクセス許可 を確認してください。
Microsoft 認証ライブラリ (MSAL) でこのアプリの登録に使用されたアプリケーション/クライアント ID を使用して、API への要求とともに送信するベアラー トークンを取得できます。
クライアント ライブラリでの API の使用については、Customer Insights クライアント ライブラリ を参照してください。
サーバー間アプリケーションのアクセス許可
ユーザー対話を必要とせず、サーバー上で実行できるアプリの登録を作成します。
Azure portal のアプリの登録で、API アクセス許可 に移動します。
アクセス許可の追加 を選択します。
所属する組織で使用している API タブを選択し、リストから Dynamics 365 AI for Customer Insights を選択します。
アクセス許可の種類では、アプリケーションのアクセス許可を選択し、api.access のアクセス許可を選択します。
アクセス許可の追加 を選択します。
アプリの登録の API アクセス許可 に戻ります。
... に管理者の同意を付与する を選択して、アプリの登録を完了します。
アプリ登録の名前を Customer Insights - Data のユーザーとして追加します。
Customer Insights - Data を開き、設定>権限に進み、ユーザーの追加を選択します。
アプリ登録の名前を検索し、検索結果から選択して、保存 を選択します。
サンプル クエリ
API で動作する OData サンプル クエリを短い一覧には、OData クエリの例 をご覧ください。
Customer Insights クライアント ライブラリ
Customer Insights - Data API に対して利用可能なクライアント ライブラリの使用を開始します。 すべてのライブラリ ソース コードとサンプル アプリケーションについては、GitHub リポジトリ を参照してください。
C# NuGet
NuGet org. からの C# クライアントライブラリを使用します。現在、このパッケージは netstandard2.0 と netcoreapp2.0 フレームワークを対象としています。 NuGet パッケージの詳細については、Microsoft.Dynamics.CustomerInsights.Api をご覧ください。
C# クライアント ライブラリを C# プロジェクトに追加する
Visual Studio で、プロジェクトのために NuGet パッケージ マネージャー を開きます。
Microsoft.Dynamics.CustomerInsights.Api を検索します。
インストール を選択し、プロジェクトにパッケージを追加します。
または、次のコマンドを NuGet パッケージ マネージャー コンソールで実行します:
Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]
C# クライアント ライブラリを使用する
Microsoft 認証ライブラリ (MSAL) を使用し、既存の Azure アプリの登録 を使用して
AccessTokenを取得します。トークンの認証と取得に成功したら、ベアラー 「アクセス トークン」 に設定された DefaultRequestHeaders 「認証」 と、ご利用の Customer Insights - Data 環境からサブスクリプション キー に設定された Ocp-Apim-Subscription-Key を使用して、新しい
HttpClientを作成するか、既存のものを使用します。必要に応じて Authorization ヘッダーをリセットします。 たとえば、トークンの有効期限が切れたときです。
この
HttpClientをCustomerInsightsクライアントの構築に渡します。クライアントで、例えば
GetAllInstancesAsyncなどの「拡張メソッド」を呼び出します。 基になるMicrosoft.Rest.HttpOperationResponseへのアクセスが推奨される場合は、たとえばGetAllInstancesWithHttpMessagesAsyncなどの "HTTP メッセージ メソッド" を使用します。この応答は
objectライプである可能性があります。なぜなら、このメソッドは複数のタイプ (例えば、IList<InstanceInfo>とApiErrorResult) を返すことができるからです。 返答の値の型を確認するには、その操作に対して API 詳細ページ で指定された応答タイプのオブジェクトを使用します。要求に関する詳細情報が必要な場合は、HTTP メッセージ メソッド を使用して、未加工の応答オブジェクトにアクセスします。
NodeJS パッケージ
NPM から入手できる NodeJS クライアント ライブラリを使用します: https://www.npmjs.com/package/@microsoft/customerinsights
Python パッケージ
PyPi から入手できる Python クライアント ライブラリを使用します: https://pypi.org/project/customerinsights/