使用 Web API 為您的組織探索 URL

文章
07/06/2017

發佈日期： 2017年1月

適用對象： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

Microsoft Dynamics 365 Web API 探索服務可讓您的應用程式在執行階段判斷登入的使用者所屬的組織，也稱為「執行個體」。您可以擷取有關這些執行個體的詳細資訊，如執行個體服務 URL、Dynamics 365 發行版本、執行個體 ID 等等。您可以對 Web API 服務要求使用標準 $filter 和 $select 參數來自訂傳回的執行個體資料清單。所有 Dynamics 365 部署類型都支援探索服務：Online、內部部署與 IFD。

用戶端應用程式可能需要存取 Dynamics 365 執行個體，其中執行個體 URL 可能隨時間改變。例如，當 Dynamics 365 執行個體從某一個 Microsoft Dynamics 365 (線上) 資料中心移到另一個時。探索服務可讓用戶端執行個體保留執行個體 ID 或執行個體唯一名稱，然後使用探索服務查詢目前執行個體存取 URL。

除了資料中心特定的探索服務之外 (可在 2011 (SOAP) 端點上及透過 Web API 使用)，另外還有僅限 Web API 的探索服務，會掃描所有營運資料中心。如需 2011 端點上探索服務的詳細資訊，請參閱使用組織服務為您的組織探索 URL。

探索服務提供的資訊

組織資訊儲存在探索服務的 Instance 實體中。若要查看該實體中包含的資訊，請傳送 HTTP GET 要求至其中一個執行個體的服務。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

在上述範例中，Microsoft Dynamics 365 (線上) 全域探索服務用來取得執行個體的組織資訊，透過唯一名稱 "myorg"。關於此要求的詳細資料，將在本主題後段詳細說明。

傳回資訊的範圍

對於全域探索服務，Instances 實體集會在未套用任何篩選時，傳回所有地理位置中使用者可存取的一組執行個體。傳回的資料範圍如下所述。

在商業雲端中包含所有執行個體，其中已佈建且啟用使用者，但是不會傳回極佳的雲端執行個體
不包括已停用使用者帳戶的執行個體
不包括已根據執行個體安全性群組將使用者篩選掉的執行個體
不包括其中使用者因為成為委派管理員而獲得存取權限的執行個體
如果呼叫使用者無法存取任何執行個體，回覆只會傳回空的清單

如何存取探索服務

一般來說，探索服務的 Web API 位址格式如下：<service base address>/api/discovery/。每個部署類型的位址會識別如下。您可以瀏覽至 [設定 > 自訂 > 開發人員資源]，如此就可在 Dynamics 365 Web 應用程式中輕鬆尋找部署的 Web API 位址和版本號碼。

Dynamics 365 (Online) 探索服務

全域探索服務的服務基底位址為：https://globaldisco.crm.dynamics.com/。這會產生服務位址 https://globaldisco.crm.dynamics.com/api/discovery/。

資料中心的探索服務的服務基底位址為：https://disco.crm[N].dynamics.com/。這會產生探索服務位址 https://disco.crm[N].dynamics.com/api/discovery/。每個資料中心都有相關聯的 N 號碼。如需可用 Microsoft Dynamics 365 (線上) 資料中心的完整清單，以及其 N 號碼，請參閱使用 Microsoft Dynamics 365 開發人員資源頁面下載端點。

內部部署和 IFD 探索服務

內部部署或 IFD 部署的探索服務的服務基底地址為：http[s]://{servername}/ 或 http[s]://dev.{servername}/。這會產生服務位址 http[s]://{servername}/api/discovery/ 或 http[s]://dev.{servername}/api/discovery/。

使用探索服務

名為「Instances」的實體集用來取得執行個體資訊。您可以使用 $select 和 $filter 搭配執行個體實體集來篩選傳回的資料。您也可以使用 $metadata 取得服務的中繼資料文件。

驗證

探索服務的 Microsoft Dynamics 365 (線上) Web API 執行個體需要使用 OAuth 存取權杖進行驗證。探索 Web API 的內部部署或 IFD 執行個體採用其部署的驗證模型，支援來自信任權杖提供者的整合式 Windows 驗證 (IWA) 或 OAuth 權杖。不支援 Web 應用程式工作階段驗證。

當探索服務設定為使用 OAuth 驗證時，傳送至服務 Web API 的要求若沒有存取權杖，就會觸發承載者權杖，透過「一般」端點和服務的資源 ID 的授權單位。同樣地，若內部部署的部署設定為使用 OAuth，則承載者權杖會傳回內部部署授權單位 URL 和服務的資源 ID。

Web API 版本管理

支援資料中心的探索服務的版本管理或內部部署/IFD，並且與組織服務使用的版本編號一致。不過，Microsoft Dynamics 365 (線上) 的全域探索服務不會繫於 Dynamics 365 部署的版本號碼。全域服務會改用自己的版本編號。截至此文截稿前，Microsoft Dynamics 365 (線上) 的全域探索服務版本為 1.0 (v1.0)。例如：

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

CORS 支援

探索服務 Web API 支援 CORS 標準進行跨原始存取，如同組織服務 Web API。如需 CORS 支援的詳細資訊，請參閱使用 OAuth 搭配跨原始來源資源共用，將單一頁面應用程式連線至 Microsoft Dynamics 365。

範例

取得特定執行個體的詳細資料。如果您跳過 GUID，已驗證使用者可存取的所有執行個體都會傳回。

GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(<guid>)
GET https://dev.crm.external.contoso.com/api/discovery/v8.1/Instances(<guid>)

您可以使用 UniqueName 屬性做為其他索引鍵。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

取得可用執行個體的清單，依生產類型篩選。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0

擷取特定執行個體的 ID 屬性值。

GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(UniqueName='myorg')/Id/$value

Microsoft Dynamics 365

分享方式：