Benutzerorganisationen suchen

Artikel
05/04/2024

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

Teilen über

Benutzerorganisationen suchen

Globaler Suchdienst

Einschränkungen

Authentifizierung

CORS-Support

Insomnia für die Herstellung einer Verbindung zum Global Discovery Service verwenden

Servicedokumente

Instance-EntitySet

Filtern

Einen der Schlüsselwerte verwenden

OData-$filter-Abfrageoptionen verwenden

Dataverse ServiceClient verwenden

CrmServiceClient verwenden

Siehe auch

Zusätzliche Ressourcen