ユーザー組織の検出

クライアント アプリケーションは、複数の Dataverse 環境に接続できます。 グローバル探索サービスを使用して、アプリケーションのユーザーがアクセスできる環境を見つけます。

Power Appsでは、使用可能な環境の一覧から選択できます。 グローバル探索サービスは、そのデータのソースです。 ユーザーが使用する環境を選択可能にする場合は、独自のアプリで選択コントロールを提供します。 選択によって、アプリが接続する必要がある環境が決まります。

Dataverse では、データセンターの管理と負荷分散の一環として、サーバーと組織の割り当てが変更される可能性があります。 そのためグローバル探索サービスには、ある特定の時点でインスタンスを処理しているサーバーを検出する方法が用意されています。

詳細情報:

• 環境の選択
• 環境の概要

Global Discovery サービス

グローバル探索サービス (GDS とも呼ばれます) は、5 つの異なるクラウドで使用できる一連の OData v4.0 エンドポイントです。

次のテーブルは、それぞれのクラウドに対する GDS の場所を示します。

詳細情報:

• Dynamics 365 米国政府
• Power Platform と Dynamics 365 アプリ - 中国で 21Vianet が運用する

制限

グローバル探索サービスは、次の場合に情報を返しません。

• ユーザーのアカウントが無効である。
• インスタンス セキュリティ グループは、ユーザーを除外します。
• ユーザーは、委任された管理者であることによってアクセス権を取得します。

呼び出し元のユーザーがインスタンスにアクセスできない場合、応答は空のリストを返します。

認証

呼び出し元のユーザーは、Microsoft Entra IDから OAuth 2.0 トークンを取得し、API 呼び出しの Authorization ヘッダーにそのトークンを追加する必要があります。 詳細については、「Microsoft Dataverseでの OAuth 認証の使用」を参照してください。

CORS サポート

検出サービスはクロスオリジン アクセスの CORS 標準に対応しています。 CORS サポートの詳細については、「 クロスオリジン リソース共有で OAuth を使用して Single-Page アプリケーションを接続する」を参照してください。

Insomnia を使用してグローバル探索サービスに接続する

Dataverse Web API での不眠症の使用に関するページの Dataverse Web API で説明されているのと同じ方法を使用します。 この記事で説明されている環境変数の代わりに、次の変数を使用して商用クラウドにアクセスします。

{
   "cloudUrl": "https://globaldisco.crm.dynamics.com",
   "globalDiscoUrl": "{{cloudUrl}}/api/discovery/v2.0/",
   "redirecturl": "https://localhost",
   "authurl": "https://login.microsoftonline.com/common/oauth2/authorize?resource={{cloudUrl}}",
   "clientid": "51f81489-12ee-4a9e-aaae-a2591f45987d"
}

[ 承認 ] タブで、[ OAuth 2 ] を選択し、次の値を設定または確認します。

GET _.globalDiscoUrl を 要求 URL として使用して 送信を選択します。

Insomnia を使用して、Global Discovery Service にクエリを実行できるようになりました。

サービス ドキュメント

各クラウドのグローバル探索サービスにアクセスするには、URL に /api/discovery/v2.0/ を追加します。 この URL に対して GET 要求を実行して、1 つの EntitySet: Instancesのみを含むサービス ドキュメントを表示します。

$metadata をクラウドの URL に付加して GET リクエストを送信し、CSDL (共通スキーマ定義言語) のサービス ドキュメントを表示します。 この XML ドキュメントは、Instance エンティティと、それに対して定義された代替キーの詳細を提供します。

インスタンス エンティティ セット

次のテーブルでは、$metadata CDSL サービス ドキュメントが含む Instance エンティティのプロパティについて説明します。

これらのプロパティ名を OData $select クエリ パラメータで使用して、必要なデータだけを取得できます。 ほとんどの場合、FriendlyName と ApiUrl プロパティのみが必要です。 例:

要求:

GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=ApiUrl,FriendlyName HTTP/1.1
Authorization: Bearer <truncated for brevity>

応答:

HTTP/1.1 200 OK
Content-Length: 625
Content-Type: application/json; odata.metadata=minimal
odata-version: 4.0

{
  "@odata.context":"https://10.0.1.76:20193/api/discovery/v2.0/$metadata#Instances(ApiUrl,FriendlyName)",
  "value":[
    {
      "ApiUrl":"https://yourorganization.api.crm.dynamics.com",
      "FriendlyName":"Your Organization"
    }
  ]
}

ユーザーが環境の名前を認識できるように、アプリケーション UI に FriendlyName プロパティを使用します。 ApiUrl を使用して Dataverse に接続します。

残りのプロパティは主にフィルターに使用します。

フィルター

返されるインスタンスは、次の 2 つの方法でフィルター処理できます。

• キー値を使用する
• OData $filter クエリ オプションを使用する

キー値を使用する

IdまたはUniqueName値を使用してリストをフィルター処理し、指定したインスタンスのみを返します。

次のどちらのクエリでも、1 つの項目を含む配列が返されます。

GET https://globaldisco.crm.dynamics.com/Instances(6bcbf6bf-1f2a-4ab9-9901-2605b314d72d)?$select=ApiUrl,FriendlyName,Id,UniqueName

GET https://globaldisco.crm.dynamics.com/Instances(UniqueName='unq6bcbf6bf1f2a4ab999012605b314d')?$select=ApiUrl,FriendlyName,Id,UniqueName

また、次のいずれかの代替キー値を使用して、特定の値 ( Region、 State、 Version) をフィルター処理することもできます。 たとえば、次のクエリを使用して、リージョンが北米を表 NA インスタンスのみを返します。

GET https://globaldisco.crm.dynamics.com/Instances(Region='NA')?$select=FriendlyName,Region,State,Version,ApiUrl

OData $filter クエリ オプションを使用する

OData $filter クエリ オプションは、代替キー のプロパティを含め、適用される任意のプロパティと共に使用できます。

次の比較演算子、論理演算子、およびグループ化演算子を使用できます。

次の文字列クエリ関数を使用できます:

Dataverse ServiceClient を使用する

.NET アプリケーションの場合は、Dataverse.Client.ServiceClient を使用します。グローバル探索サービスを呼び出す DiscoverOnlineOrganizationsAsync メソッド。

 // Set up user credentials
var creds = new System.ServiceModel.Description.ClientCredentials();
creds.UserName.UserName = userName;
creds.UserName.Password = password;

//Call DiscoverOnlineOrganizationsAsync
DiscoverOrganizationsResult organizationsResult = await ServiceClient.DiscoverOnlineOrganizationsAsync(
        discoveryServiceUri: new Uri($"{cloudRegionUrl}/api/discovery/v2.0/Instances"),
        clientCredentials: creds,
        clientId: clientId,
        redirectUri: new Uri(redirectUrl),
        isOnPrem: false,
        authority: "https://login.microsoftonline.com/organizations/",
        promptBehavior: PromptBehavior.Auto);

return organizationsResult;

DiscoverOnlineOrganizationsAsync メソッドは同じ OData エンドポイントを使用し、discoveryServiceUri パラメーターで渡すことができますが、インスタンスの形でデータを返しません。 これは、OrganizationDetail クラス インスタンスのコレクションを含む OrganizationDetailCollection プロパティを含む DiscoverOrganizationsResult クラスとしてデータを返します。 このクラスは、OData サービスによって返される Instance タイプと同じ情報を含みます。

CrmServiceClient を使用する

.NET Framework アプリケーションの場合は、引き続き CrmServiceClient.DiscoverGlobalOrganizations メソッドを使用してグローバル探索サービスを呼び出します。

  // Set up user credentials
  var creds = new System.ServiceModel.Description.ClientCredentials();
  creds.UserName.UserName = userName;
  creds.UserName.Password = password;

  // Call to get organizations from global discovery
  var organizations = CrmServiceClient.DiscoverGlobalOrganizations(
        discoveryServiceUri:new Uri($"{cloudRegionUrl}/api/discovery/v2.0/Instances"), 
        clientCredentials: creds, 
        user: null, 
        clientId: clientId,
        redirectUri: new Uri(redirectUrl), 
        tokenCachePath: "",
        isOnPrem: false,
        authority: string.Empty, 
        promptBehavior: PromptBehavior.Auto);

  return organizations.ToList();

ServiceClient.DiscoverOnlineOrganizationsAsync メソッドと同様に、CrmServiceClient.DiscoverGlobalOrganizations メソッドもインスタンスとしてデータを返しません。 これは、OrganizationDetail クラス インスタンスのコレクションを含む OrganizationDetailCollection を返します。 このコレクションには、OData サービスによって返される Instance 型と同じ情報が含まれています。

関連情報

サンプル: グローバル探索サービス (C#)
サンプル: CrmServiceClient を使用して探索サービスにアクセスする
サンプル: グローバル検索を利用した Blazor WebAssembly