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

注意

Effective November 2020:

  • Common Data Service has been renamed to Microsoft Dataverse. Learn more
  • Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more

This article will be updated soon to reflect the latest terminology.

検出サービス 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 呼び出しの認証ヘッダーに追加します。 詳細については Common Data Service で 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 を使用した検出サービスから返される応答のフィールド マッピングを示しています。 これらは、前述のすべての呼び出し例に対応しています。

応答フィールド(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 では対応していません。

    関連項目

    検出サービス

    Common Data Service Web API を使用する