使用 Customer Insights - Data API

發行項
03/26/2024

Dynamics 365 Customer Insights - Data 提供 API，可根據 Customer Insights 中的資料建立您自己的應用程式。這些 API 詳細資料會列在 API 參考中。它們包含有關作業、參數和回應的其他資訊。

注意

也可以使用 Dataverse API 存取 Customer Insights - Data 資料表。由於 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 入口網站建立新的應用程式註冊

建立新的應用程式註冊，透過委派權限在 Azure 應用程式中使用 API。

完成開始使用區段。
使用可存取 Customer Insights 資料的帳戶登入 Azure 入口網站。
搜尋然後選取應用程式註冊。
選取新增註冊提供應用程式名稱並選擇帳戶類型。

或者新增重新導向 URL。 http://localhost 足以用來開發本機電腦上的應用程式。
選取註冊。
在您的新應用程式註冊上前往 API 權限。
選取新增權限，並選取側邊窗格中的 Dynamics 365 AI for Customer Insights。
在權限類型中，選取委派權限，然後選取 user_impersonation 權限。
選取新增權限。
選取 授與系統管理員同意... 完成應用程式註冊。
若要在使用者未登入的情況下存取 API，請移至設定伺服器對伺服器應用程式權限區。

您可以將此應用程式註冊的應用程式/用戶端識別碼與 Microsoft 驗證程式庫 (MSAL) 搭配使用，取得持有人權杖，以便與隨您的要求一起傳送至 API。

如需在用戶端程式庫中使用 API 的更多資訊，請參閱Customer Insights 用戶端程式庫。

設定伺服器對伺服器應用程式權限

建立不需要使用者互動且可在伺服器上執行的應用程式註冊。

在 Azure 入口網站中您的應用程式註冊上，前往 API 權限。
選取新增權限。
選取我的組織使用的 API 索引標籤，然後從清單中選擇Dynamics 365 AI for Customer Insights。
在權限類型中，選取應用程式權限，然後選取 api.access 權限。
選取新增權限。
返回 API 權限進行應用程式註冊。
選取 授與系統管理員同意... 完成應用程式註冊。
將應用程式註冊的名稱新增為 Customer Insights - Data 中的使用者。
1. 開啟 Customer Insights - Data、移至設定>權限，並選取新增使用者。
2. 搜尋您的應用程式註冊名稱，從搜尋結果選取它，然後選取儲存。

範例查詢

有關要與 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) 取得 AccessToken 使用現有的 Azure 應用程式註冊。
成功驗證並獲取權杖之後，建構新的或使用現有的 HttpClient，並將 DefaultRequestHeaders "Authorization" 設定為 Bearer "access token"，然後將 Ocp-Apim-Subscription-Key 設定為 Customer Insights - Data 環境中的訂閱金鑰。

請適時重設授權標頭。例如當權杖到期時。
將此 HttpClient 傳遞到 CustomerInsights 用戶端的建構過程。
讓用戶端與「擴充方法」通話，例如，GetAllInstancesAsync。如果偏好存取基礎 Microsoft.Rest.HttpOperationResponse，請使用「HTTP 訊息方法」，例如 GetAllInstancesWithHttpMessagesAsync。
回應類型很有可能是 object，因為此方法可以傳回多個類型 (例如，IList<InstanceInfo> 和 ApiErrorResult)。若要檢查傳回類型，請使用該作業的 API 詳細資料頁面所指定回應類型中的物件。

如果需要更多要求資訊，請使用 HTTP 訊息方法 存取原始回應物件。

NodeJS 套件

可透過 NPM 使用 NodeJS 用戶端程式庫：https://www.npmjs.com/package/@microsoft/customerinsights

Python 套件

可透過 PyPi 使用 Python 用戶端程式庫：https://pypi.org/project/customerinsights/

共用方式為