ユーザー組織の検出

[アーティクル]
03/14/2024

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

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

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

詳細情報:

グローバル探索サービス

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

注意

Dataverse Web API とグローバル探索サービスは、両方とも OData v4.0 エンドポイントですが、これらは動作が異なる別個のエンドポイントです。

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

クラウド	URL と説明
商用	`https://globaldisco.crm.dynamics.com` 民間企業が使用します。これは最も一般的に使用されるクラウドです。
GCC	`https://globaldisco.crm9.dynamics.com` Government Community Cloud。米国の公的部門の従業員と請負業者が使用します。
USG	`https://globaldisco.crm.microsoftdynamics.us` 米国連邦政府の従業員および請負業者が使用します。 GCC High VSTS と呼ばれることもあります。
DOD	`https://globaldisco.crm.appsplatform.us` 米国国防総省の従業員および請負業者が使用します。
中国	`https://globaldisco.crm.dynamics.cn` 規制要件に準拠するために中国の企業が使用します。

詳細情報:

制限

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

ユーザーのアカウントが無効である。
インスタンスセキュリティグループに基づいてユーザーが除外されている。
ユーザーが代理管理者であるためアクセス権を持っている。

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

認証

呼び出し側ユーザーは、Microsoft Entra ID から OAuth 2.0 トークンを取得し、そのトークンを API 呼び出しの Authorization ヘッダーに追加する必要があります。詳細情報: Microsoft Dataverse で OAuth 認証を使用する。

CORS サポート

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

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

Dataverse Web API には、次で説明されている同じ方法を使用できます: Dataverse Web API を含む Insomnia を使用する、ただし、トピックで説明されている環境変数の代わりに、以下を使用して商用クラウドにアクセスします。

{
   "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 を選択して、次の値を設定または確認します。

フィールド	価値
付与タイプ	暗黙
認証 URI	`_.authurl`
CLIENTID	`_.clientid`
リダイレクト URL	`_.redirecturl`

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

これで、Insomnia を使用してグローバル探索サービスにクエリを実行できるようになります。

サービスドキュメント

それぞれのクラウドでグローバル探索サービスにアクセスする際は、URL に /api/discovery/v2.0/ を付加します。この URL で GET リクエストを実行して、単一の EntitySet: Instances のみを含むサービスドキュメントを表示します。

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

インスタンス EntitySet

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

プロパティ	タイプ	説明
`ApiUrl`	文字列	クライアントアプリケーションが使用する Web サービスの場所。
`DatacenterId`	文字列	インスタンスが配置されたデータセンターの ID。
`DatacenterName`	文字列	インスタンスが配置されたデータセンターの名前。通常、この値は null です。
`EnvironmentId`	文字列	インスタンスの EnvironmentId。
`FriendlyName`	文字列	インスタンスの名前。powerapps.com と、インスタンスを選択できるその他のクライアントアプリケーションに表示します。
`Id`	GUID	環境の OrganizationId。
`IsUserSysAdmin`	ブール値	環境のシステム管理者ロールを呼び出し元のユーザーが持っているかどうか。
`LastUpdated`	DateTimeOffset	環境を最後に更新した日時。
`OrganizationType`	Int32	組織の種類。 OrganizationType EnumType に対応する値
`Purpose`	文字列	環境の作成時に提供した目的の情報。
`Region`	文字列	環境が配置された地域を表す 2 ～ 3 文字のコード。
`SchemaType`	文字列	内部でのみ使用します。
`State`	Int32	組織が有効 (`0`) か無効 (`1`) か。
`StatusMessage`	Int32	次のいずれかの値: `0`:`InstanceLocked` `1`:`PendingServiceInstanceMove` `2`:`InstanceFailed` `3`:`Provisioning` `4`:`InActiveOrganizationStatus` `5`:`NewInstance` `6`:`InstancePickerReady`
`TenantId`	GUID	インスタンスに関連付けられたテナントの ID
`TrialExpirationDate`	DateTimeOffset	インスタンスの試用期間が終了する日付。
`UniqueName`	文字列	インスタンスを表す一意の名前。
`UrlName`	文字列	URL に使用する名前。
`Version`	文字列	環境の現在のバージョン。
`Url`	文字列	環境のアプリケーション URL。

これらのプロパティ名を 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 の値を使用してリストをフィルターできます。

注意

Dataverse Web API とは異なり、グローバル探索サービスは Id や、それに対して定義された代替キーのいずれかを使用して、特定の Instance を取得できません。 GDS は常に値の配列を返します。

これらのクエリは両方とも、単一の項目を含む配列です:

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 クエリオプションは、代替キープロパティなど、適用する任意のプロパティと共に使用できます。

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

演算子	説明	例
比較演算子
`eq`	等しい	`$filter=IsUserSysAdmin eq true`
`ne`	等しくない	`$filter=IsUserSysAdmin ne true`
`gt`	より大きい	`$filter=TrialExpirationDate gt 2022-07-14T00:00:00Z`
`ge`	以上	`$filter=TrialExpirationDate ge 2022-07-14T00:00:00Z`
`lt`	より小さい	`$filter=TrialExpirationDate lt 2022-07-14T00:00:00Z`
`le`	以下	`$filter=TrialExpirationDate le 2022-07-14T00:00:00Z`
論理演算子
`and`	論理積	`$filter=TrialExpirationDate gt 2022-07-14T00:00:00Z and IsUserSysAdmin eq true`
`or`	論理和	`$filter=TrialExpirationDate gt 2022-07-14T00:00:00Z or IsUserSysAdmin eq true`
`not`	論理否定	`$filter=not contains(Purpose,'test')`
グループ化演算子
`( )`	優先順位のグループ化	`(contains(Purpose,'sample') or contains(Purpose,'test')) and TrialExpirationDate gt 2022-07-14T00:00:00Z`

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

関数	例
`contains`	`$filter=contains(Purpose,'test')`
`endswith`	`$filter=endswith(FriendlyName,'Inc.')`
`startswith`	`$filter=startswith(FriendlyName,'A')`

注意

Dataverse Web API とは異なり、グローバル探索サービスの検索文字列は大文字と小文字を区別します。

Dataverse ServiceClient を使用する

.NET アプリケーションでは Dataverse.Client.ServiceClient.DiscoverOnlineOrganizationsAsync Method を使用してグローバル探索サービスを呼び出せます。

 // 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 Class インスタンスのコレクションを格納した OrganizationDetailCollection Property を含む、DiscoverOrganizationsResult Class としてデータを返します。このクラスは、OData サービスによって返される Instance タイプと同じ情報を含みます。

注意

DiscoverOnlineOrganizationsAsync.discoveryServiceUri パラメーターにはグローバル探索サービスの URL を使用できますが、使用する $select や $filter クエリオプションはすべて無視されます。 DiscoverOnlineOrganizationsAsync.discoveryServiceUri パラメーターはオプションであり、指定しないと既定の商用クラウドになります。

CrmServiceClient を使用する

.NET Framework アプリケーションの場合、引き続き CrmServiceClient.DiscoverGlobalOrganizations Method を使用して Global Discovery Service を呼び出すことができます。

  // 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 メソッドも インスタンス としてデータを返しません。 OData サービスが返す Instance タイプと同じ情報を格納した、OrganizationDetail Class インスタンスのコレクションを含む OrganizationDetailCollection を返します。

次の方法で共有

ユーザー組織の検出

グローバル探索サービス

制限

認証

CORS サポート

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

サービスドキュメント

インスタンス EntitySet

フィルター

いずれかのキー値を使用する

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

Dataverse ServiceClient を使用する

CrmServiceClient を使用する

関連情報

その他のリソース

次の方法で共有

ユーザー組織の検出

グローバル探索サービス

制限

認証

CORS サポート

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

サービス ドキュメント

インスタンス EntitySet

フィルター

いずれかのキー値を使用する

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

Dataverse ServiceClient を使用する

CrmServiceClient を使用する

関連情報

その他のリソース

サービスドキュメント

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