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

Der aufrufende Benutzer muss 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.

Postman verwenden, um eine Verbindung zum globalen Suchdienst herzustellen

Sie können den gleichen Ansatz verwenden, der für die Dataverse Web-API hier beschrieben wurde: Einrichten einer Postman-Umgebung, aber anstelle der in diesem Thema beschriebenen Umgebungsvariablen verwenden Sie Folgendes, um auf die gewerbliche Cloud zuzugreifen.

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

Dann in Postman auf der Registerkarte Authorization legen Sie die folgenden Werte fest oder überprüfen sie:

Feld Wert
Type OAuth 2.0
Add authorization data to Request Headers
Header Prefix Bearer
Grant Type Implicit
Callback URL http://localhost
Auth URL {{authurl}}
Client ID {{clientid}}
Client Authentication Send as Basic Auth header

Verwenden Sie {{globalDiscoUrl}} als Anforderungs-URL, und klicken Sie auf der Registerkarte Authorization auf Get New Access Token.

Sie sollten jetzt den globalen Suchdienst mit Postman abfragen können.

Weitere Informationen: YouTube: Erste Schritte mit Postman mit Microsoft Dataverse Web-API

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).