ユーザー組織の検出
クライアント アプリケーションが複数の 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.comGovernment 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:InstanceLocked1:PendingServiceInstanceMove2:InstanceFailed3:Provisioning 4:InActiveOrganizationStatus5:NewInstance6: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 を返します。
関連情報
サンプル: グローバル探索サービス (C#)
サンプル: CrmServiceClient を使用して探索サービスにアクセスする
サンプル: グローバル検索を利用した Blazor WebAssembly
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示