コードを変更してグローバル検出サービスを使用する

[アーティクル]
03/04/2022

Discovery Service API をアプリケーションで使用して、アプリケーションユーザーがアクセスできるビジネス組織インスタンス (環境) を検出できます。アプリケーションが現在 2011 SOAPエンドポイントで Organization Service API を使用して組織インスタンスを検出している場合、このトピックの手順に従って、OData V4 RESTful API とグローバル検出サービスの URL を使用して組織の詳細にアクセスするようにアプリケーションを変換できます。アプリケーションが地域の検出サービスの URLを使用して検出サービスにアクセスする場合は、アプリケーションコードを地域のURLを使用したものからグローバルな検出サービスの URL に変更する必要があります。

RESTful API を使用した検出サービスに関する詳細な解説は、組織のURLを見つけるページを参照してください。

重要

検出サービスへのアクセスには、 グローバル 検出サービスエンドポイント (https://globaldisco.crm.dynamics.com) を使用することを強く推奨します。 地域型 検出サービスエンドポイントは、2020年3月2日で廃止となります。グローバル検出サービスは、RESTful API を使用している場合にのみ利用可能となります。

RESTful API を使用して検出サービスを呼び出すにあたって必要な変更について以下で解説します。

認証

RESTful API を使用した検出サービスのへのアクセスには、OAuth 2.0 アクセストークンを使用した認証が必要となります。アプリケーションコードが認証に WS-Trust SAML トークンを使用する場合は、アプリケーションコードを変更して、Azure Active Directory (AD) から OAuth 2.0 トークンを取得する必要があります。続いてそのトークンを、検出サービス API 呼び出しの認証ヘッダーに追加します。詳細については Microsoft Dataverse で OAuth を使用するを参照してください: 。

OData API 呼び出し

以下に示す HTTP リクエストの例は、検出サービス RESTful API で対応することができます。これらの例では、インスタンス API を使用して、組織サービス API の RetrieveOrganizationsRequest および RetrieveOrganizationRequest メッセージ要求と同じ組織データを戻します。

すべての地域のユーザーのすべてのインスタンスを取得します。

GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances

特定の地域のユーザーのすべてのインスタンスを取得します。

GET  https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(Region='{region}')

応答

{
  "value":[
    {
      "Id":"<GUID>",
      "UniqueName":"myorg",
      "UrlName":"orgurlname",
      "FriendlyName":"My Org",
      "State":0,
      "Version":"<Version>",
      "Url":"https://orgurlname.crm.dynamics.com",
      "ApiUrl":"https://orgurlname.api.crm.dynamics.com"
    }
  ]
}

ID で単一のインスタンスを取得する

GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(<guid>)

一意の名称で単一のインスタンスを取得する

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

回答

{
  "Id":"<GUID>",
  "UniqueName":"myorg",
  "UrlName":"orgurlname",
  "FriendlyName":"My Org",
  "State":0,
  "Version":"<Version>",
  "Url":"https://orgurlname.crm.dynamics.com",
  "ApiUrl":"https://orgurlname.api.crm.dynamics.com"
}

列のマッピング

以下の表は、2つの API を使用したときに Discovery Service から返される応答の列マッピングを示しています。これらは、前述のすべての呼び出し例に対応しています。

応答フィールド（SOAP エンドポイント）	応答フィールド（OData V4 RESTful エンドポイント）
エンドポイント [WebApplication]	Url
エンドポイント [OrganizationService]	{ApiUrl}/XRMServices/2011/Organization.svc
エンドポイント [OrganizationDataService]	{ApiUrl}//XRMServices/2011/OrganizationData.svc
FriendlyName	FriendlyName
OrganizationId	ID
OrganizationVersion	[バージョン]
都道府県	都道府県 0 : 有効 1 : 無効
UniqueName	UniqueName
UrlName	UrlName

廃止される API 呼び出し

組織サービスの API メッセージ GetUserIdByExternalId は、RESTful API では対応していません。

コードを変更してグローバル検出サービスを使用する

認証

OData API 呼び出し

列のマッピング

廃止される API 呼び出し

関連項目

フィードバック