Benutzerorganisationen suchen
Ihre Client-Anwendung kann eine Verbindung zu mehreren Dataverse-Umgebungen herstellen. Verwenden Sie den globalen Suchdienst, um herauszufinden, auf welche Umgebungen der Benutzer Ihrer Anwendung zugreifen kann.
In Power Apps können Sie aus einer Liste verfügbarer Umgebungen auswählen. Der globale Suchdienst ist die Quelle dieser Daten. In Ihrer eigenen App können Sie ein Auswahlsteuerelement bereitstellen, mit dem Benutzer auswählen können, welche Umgebung sie verwenden möchten. Ihre Wahl bestimmt, mit welcher Umgebung sich Ihre App verbinden muss.
Bei Dataverse kann sich die Zuweisung von Server und Organisation bedingt durch Rechenzentrumsverwaltung und Lastenausgleich ändern. Daher kann mithilfe des globalen Suchdienstes ermittelt werden, welcher Server zu einer gegebenen Zeit eine Instanz bereitstellt.
Weitere Informationen:
Globaler Suchdienst
Der globale Suchdienst, manchmal auch GDS (Global Discovery Service) genannt, ist eine Reihe von OData v4.0-Endpunkten, die für 5 verschiedene Clouds verfügbar sind.
Hinweis
Während die Dataverse Web-API und der globale Suchdienst OData v4.0-Endpunkte sind, sind sie separate Endpunkte mit unterschiedlichem Verhalten.
In der folgenden Tabelle werden die GDS-Standorte für jede Cloud bereitgestellt.
Cloud | URL und Beschreibung |
---|---|
Commercial | https://globaldisco.crm.dynamics.com Wird von Unternehmen des privaten Sektors verwendet. Diese Cloud wird am häufigsten verwendet. |
GCC | https://globaldisco.crm9.dynamics.com Government Community Cloud. Wird von Mitarbeitern des öffentlichen Sektors und Auftragnehmern in den Vereinigten Staaten verwendet. |
USG | https://globaldisco.crm.microsoftdynamics.us Wird von Mitarbeitern und Auftragnehmern der US-Bundesregierung verwendet. Auch als GCC High bekannt. |
DOD | https://globaldisco.crm.appsplatform.us Wird von Mitarbeitern und Auftragnehmern des US-Verteidigungsministeriums verwendet. |
China | https://globaldisco.crm.dynamics.cn Wird von Unternehmen in China verwendet, sodass sie den gesetzlichen Anforderungen entsprechen. |
Weitere Informationen:
Einschränkungen
Der globale Suchdienst gibt keine Informationen in folgenden Fällen zurück:
- Das Benutzerkonto ist deaktiviert.
- Benutzer wurden auf Basis einer Instanzsicherheitsgruppe herausgefiltert.
- Der Benutzer hat Zugriff, da er ein stellvertretender Administrator ist.
Wenn der aufrufende Benutzer Zugriff auf keine Instanzen hat, gibt die Antwort einfach eine leere Liste zurück.
Authentifizierung
Aufrufende Benutzende müssen ein OAuth 2.0-Token von Microsoft Entra ID erwerben und dann dieses Token in den Autorisierungsheader der API-Aufrufe hinzufügen. Weitere Informationen: OAuth-Authentifizierung mit Microsoft Dataverse verwenden.
CORS-Support
Der Ermittlungsdienst unterstützt den CORS-Standard für den ursprungsübergreifenden Zugriff. Für weitere Informationen zum CORS-Support siehe Verwenden von OAuth mit Cross-Origin Resource Sharing, um eine Single Page-Anwendung zu verbinden.
Insomnia für die Herstellung einer Verbindung zum Global Discovery Service verwenden
Sie können den gleichen Ansatz verwenden, der hier für die Dataverse-Web-API beschrieben wurde: Insomnia mit der Dataverse-Web-API verwenden. Verwenden Sie aber statt der in diesem Thema beschriebenen Umgebungsvariablen die folgenden, um auf die kommerzielle Cloud zuzugreifen.
{
"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"
}
Wählen Sie dann auf der Registerkarte Autorisierung OAuth 2 aus, legen Sie die folgenden Werte fest oder überprüfen Sie sie:
Feld | Wert |
---|---|
GEWÄHRUNGSTYP | Implizit |
AUTORISIERUNGS-URL | _.authurl |
CLIENTID | _.clientid |
UMLEITUNGS-URL | _.redirecturl |
Verwenden Sie GET _.globalDiscoUrl
als Anforderungs-URL und wählen Sie Senden.
Sie sollten den Global Discovery Service nun mit Insomnia abfragen können.
Servicedokumente
Um auf den globalen Suchdienst für jede Cloud zuzugreifen, fügen Sie /api/discovery/v2.0/
an die URL an. Führen Sie eine GET
-Anforderung unter dieser URL aus, um das Servicedokument anzuzeigen, das nur ein einziges EntitySet enthält: Instances
.
Fügen Sie $metadata
an die Cloud-URL and und senden Sie eine GET
-Anforderung zum Anzeigen des CSDL-Servicedokuments (Common Schema Definition Language). Dieses XML-Dokument enthält Einzelheiten zur Instance
-Entität und die dafür definierten Alternativschlüssel.
Instance-EntitySet
Die folgende Tabelle beschreibt die Eigenschaften der Instance
-Entität aus dem $metadata-CDSL-Servicedokument.
Eigenschaft | Typ | Beschreibung |
---|---|---|
ApiUrl |
Zeichenfolge | Der Speicherort von Clientanwendungen für Webdienste, die verwendet werden sollten. |
DatacenterId |
Zeichenfolge | Die ID des Rechenzentrums, in dem sich die Instanz befindet. |
DatacenterName |
Zeichenfolge | Der Name des Rechenzentrums, in dem sich die Instanz befindet. Dieser Wert ist normalerweise null. |
EnvironmentId |
Zeichenfolge | Die EnvironmentId für die Instanz. |
FriendlyName |
Zeichenfolge | Ein Name für die Instanz, der in powerapps.com und anderen Clientanwendungen angezeigt wird, die die Auswahl von Instanzen ermöglichen. |
Id |
GUID | Die OrganizationId für die Umgebung. |
IsUserSysAdmin |
Boolesch | Ob der aufrufende Benutzer die Systemadministratorrolle für die Umgebung hat. |
LastUpdated |
DateTimeOffset | Wann die letzte Aktualisierung der Umgebung war. |
OrganizationType |
Int32 | Der Typ der Organisation. Werte entsprechen OrganizationType EnumType |
Purpose |
Zeichenfolge | Informationen für den Zweck, die bereitgestellt wurden, als die Umgebung erstellt wurde. |
Region |
Zeichenfolge | Ein aus 2-3 Buchstaben bestehender Code für die Region, in der sich die Umgebung befindet. |
SchemaType |
Zeichenfolge | Nur zur internen Verwendung. |
State |
Int32 | Ob die Organisation 0 :enabled (aktiviert) oder 1 :disabled (deaktiviert) ist. |
StatusMessage |
Int32 | Einer der folgenden Werte: 0 :InstanceLocked 1 :PendingServiceInstanceMove 2 :InstanceFailed 3 :Provisioning 4 :InActiveOrganizationStatus 5 :NewInstance 6 :InstancePickerReady |
TenantId |
GUID | Die ID des Mandanten, der mit der Instanz verknüpft ist |
TrialExpirationDate |
DateTimeOffset | Das Datum, an dem der Testzeitraum für die Instanz abläuft. |
UniqueName |
Zeichenfolge | Der eindeutige Name für die Instanz. |
UrlName |
Zeichenfolge | Der für die URL verwendete Name. |
Version |
Zeichenfolge | Die aktuelle Version der Umgebung. |
Url |
Zeichenfolge | Die Anwendungs-URL für die Umgebung. |
Sie können diese Eigenschaftsnamen mit dem OData-Abfrageparameter $select
verwenden, um nur die Daten abzurufen, die Sie benötigen. In den meisten Fällen benötigen Sie lediglich die Eigenschaften FriendlyName
und ApiUrl
. Zum Beispiel:
Anforderung:
GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=ApiUrl,FriendlyName HTTP/1.1
Authorization: Bearer <truncated for brevity>
Antwort:
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"
}
]
}
Verwenden Sie die FriendlyName
-Eigenschaft für die Benutzeroberfläche Ihrer Anwendung, damit der Benutzer den Namen der Umgebung erkennt. Verwenden Sie ApiUrl
, um eine Verbindung mit Dataverse herzustellen.
Die restlichen Eigenschaften dienen hauptsächlich zum Filtern.
Filtern
Es gibt zwei Möglichkeiten, die zurückgegebenen Instanzen zu filtern:
- Mit Schlüsselwerten
- Mit OData-
$filter
-Abfrageoptionen
Einen der Schlüsselwerte verwenden
Mit dem Id
- oder UniqueName
-Wert können Sie die Liste filtern, um nur die angegebene Instanz zurückzugeben.
Hinweis
Im Gegensatz zur Dataverse Web-API bietet der globale Suchdienst kein Abrufen einer bestimmten Instance
unter Verwendung der Id
oder eines dafür definierten Alternativschlüssels. GDS gibt immer ein Array von Werten zurück.
Diese beiden Abfragen werden ein Array mit einem einzigen Element sein:
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
Sie können auch einen der folgenden Alternativschlüssel-Werte verwenden: Region
, State
, Version
, um nach bestimmten Werten zu filtern. Verwenden Sie beispielsweise die folgende Abfrage, um nur die Instanzen zurückzugeben, in denen die Region NA
, also Nordamerika ist.
GET https://globaldisco.crm.dynamics.com/Instances(Region='NA')?$select=FriendlyName,Region,State,Version,ApiUrl
OData-$filter-Abfrageoptionen verwenden
Sie können auch OData-$filter
-Abfrageoptionen mit allen zutreffenden Eigenschaften verwenden, einschließlich der Alternativschlüssel-Eigenschaften.
Sie können die folgenden Vergleichs-, Logik- und Gruppierungsoperatoren verwenden:
Operator | Beschreibung | Beispiel |
---|---|---|
Vergleichsoperatoren | ||
eq |
Gleich | $filter=IsUserSysAdmin eq true |
ne |
Ungleich | $filter=IsUserSysAdmin ne true |
gt |
Größer als | $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z |
ge |
Größer als oder gleich | $filter=TrialExpirationDate ge 2022-07-14T00:00:00Z |
lt |
Kleiner als | $filter=TrialExpirationDate lt 2022-07-14T00:00:00Z |
le |
Kleiner oder gleich | $filter=TrialExpirationDate le 2022-07-14T00:00:00Z |
Logische Operatoren | ||
and |
Logisch und | $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z and IsUserSysAdmin eq true |
or |
Logisch oder | $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z or IsUserSysAdmin eq true |
not |
Logische Negation | $filter=not contains(Purpose,'test') |
Gruppierungsoperatoren | ||
( ) |
Rangfolgengruppierung | (contains(Purpose,'sample') or contains(Purpose,'test')) and TrialExpirationDate gt 2022-07-14T00:00:00Z |
Sie können die folgenden Zeichenfolgen-Abfragefunktionen verwenden:
Funktion | Beispiel |
---|---|
contains |
$filter=contains(Purpose,'test') |
endswith |
$filter=endswith(FriendlyName,'Inc.') |
startswith |
$filter=startswith(FriendlyName,'A') |
Hinweis
Im Gegensatz zur Dataverse Web-API wird bei Suchzeichenfolgen für den globalen Suchdienst zwischen Groß- und Kleinschreibung unterschieden.
Dataverse ServiceClient verwenden
Für .NET-Anwendungen können Sie Dataverse.Client.ServiceClient.DiscoverOnlineOrganizationsAsync Method verwenden, um die globalen Suchdienste aufzurufen.
// 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;
Während die DiscoverOnlineOrganizationsAsync
-Methode denselben OData-Endpunkt verwendet und ermöglicht, dass er im discoveryServiceUri
-Parameter übergeben wird, gibt sie keine Daten in Form einer Instanz zurück. Die Daten werden als DiscoverOrganizationsResult Class zurückgegeben, die eine OrganizationDetailCollection Property beinhaltet, die eine Sammlung von OrganizationDetail Class-Instanzen enthält. Diese Klasse enthält die gleichen Informationen wie die Instance
-Typen, die vom OData-Service zurückgegeben werden.
Hinweis
Während der DiscoverOnlineOrganizationsAsync.discoveryServiceUri
-Parameter eine URL zum globalen Suchdienst akzeptiert, werden alle verwendeten $select
- oder $filter
-Abfrageoptionen ignoriert. Der DiscoverOnlineOrganizationsAsync.discoveryServiceUri
-Parameter ist optional und wird, wenn er nicht angegeben wird, standardmäßig auf die Commercial-Cloud gesetzt.
CrmServiceClient verwenden
Für .NET Framework-Anwendungen können Sie weiterhin die CrmServiceClient.DiscoverGlobalOrganizations Method verwenden, um den Global Discovery Service anzurufen.
// 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();
Wie die ServiceClient.DiscoverOnlineOrganizationsAsync
-Methode gibt auch die CrmServiceClient.DiscoverGlobalOrganizations
-Methode keine Daten als Instanz zurück. Sie gibt OrganizationDetailCollection zurück, die eine Sammlung von OrganizationDetail Class-Instanzen enthält, die dieselben Informationen wie die Instance
-Typen enthalten, die vom OData-Service zurückgegeben werden.
Siehe auch
Beispiel: Globaler Suchdienst-Beispiel (C#)
Beispiel: Zugreifen auf den Suchdienst mit CrmServiceClient
Beispiel: Blazor WebAssembly mit globaler Ermittlung
Hinweis
Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)
Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).