Benutzerorganisationen suchen

Ihre Clientanwendung kann eine Verbindung mit 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 der verfügbaren 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 Ihre App eine Verbindung herstellen muss.

Mit Dataverse können sich die Server- und Organisationszuordnung im Rahmen der Rechenzentrumsverwaltung und des Lastenausgleichs ändern. Daher kann mithilfe des globalen Suchdienstes ermittelt werden, welcher Server zu einer gegebenen Zeit eine Instanz bereitstellt.

Weitere Informationen:

• Umgebung auswählen
• Übersicht zu Umgebungen

Global Discovery-Dienst

Der Global Discovery-Dienst, manchmal als GDS bezeichnet, ist eine Reihe von OData v4.0-Endpunkten, die für fünf verschiedene Clouds verfügbar sind.

In der folgenden Tabelle werden die GDS-Standorte für jede Cloud bereitgestellt.

Weitere Informationen:

• Dynamics 365 US Government
• Power Platform- und Dynamics 365-Apps – ausgeführt von 21Vianet in China

Einschränkungen

Der globale Ermittlungsdienst gibt keine Informationen zurück, wenn:

• Das Benutzerkonto ist deaktiviert.
• Eine Instanzsicherheitsgruppe filtert den Benutzer heraus.
• Der Benutzer erhält Zugriff, indem er ein delegierter Administrator ist.

Wenn der aufrufende Benutzer nicht auf Instanzen zugreifen kann, gibt die Antwort eine leere Liste zurück.

Authentifizierung

Der aufrufende Benutzer muss ein OAuth 2.0-Token aus Microsoft Entra ID abrufen und dieses Token im Autorisierungsheader der API-Aufrufe hinzufügen. Weitere Informationen finden Sie unter Verwenden der OAuth-Authentifizierung mit Microsoft Dataverse.

CORS-Support

Der Ermittlungsdienst unterstützt den CORS-Standard für den ursprungsübergreifenden Zugriff. Weitere Informationen zur CORS-Unterstützung finden Sie unter 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

Verwenden Sie den gleichen Ansatz, der für die Dataverse-Web-API in Verwendung von Schlaflosigkeit mit Dataverse Web-API beschrieben wird. Verwenden Sie anstelle der in diesem Artikel beschriebenen Umgebungsvariablen die folgenden Variablen, 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 auf der Registerkarte "Autorisierung " OAuth 2 aus, und legen Sie die folgenden Werte fest, oder überprüfen Sie sie:

Verwenden Sie GET _.globalDiscoUrl als Anforderungs-URL und wählen Sie Senden.

Sie können den Global Discovery Service jetzt mit Insomnia abfragen.

Servicebelege

Um auf den globalen Ermittlungsdienst für jede Cloud zuzugreifen, fügen Sie die URL an /api/discovery/v2.0/ . Führen Sie eine GET Anforderung für diese URL aus, um das Dienstdokument anzuzeigen, das nur ein einzelnes 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.

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.

Filterung

Sie können die zurückgegebenen Instanzen auf zwei Arten filtern:

• Verwenden von Schlüsselwerten
• Mit OData-$filter-Abfrageoptionen

Verwenden von Schlüsselwerten

Verwenden Sie den Id Wert, UniqueName um die Liste zu filtern und nur die angegebene Instanz zurückzugeben.

Beide der folgenden Abfragen geben ein Array mit einem einzelnen Element zurück:

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 eine der folgenden alternativen Schlüsselwerte verwenden, um nach bestimmten Werten zu filtern: Region, , . StateVersion Verwenden Sie beispielsweise die folgende Abfrage, um nur die Instanzen zurückzugeben, in denen die Region NA Nordamerika darstellt.

GET https://globaldisco.crm.dynamics.com/Instances(Region='NA')?$select=FriendlyName,Region,State,Version,ApiUrl

OData-$filter-Abfrageoptionen verwenden

Sie können OData-$filterAbfrageoptionen mit allen zutreffenden Eigenschaften verwenden, einschließlich der Eigenschaften des alternativen Schlüssels.

Sie können die folgenden Vergleichs-, logischen und Gruppierungsoperatoren verwenden:

Sie können die folgenden Zeichenfolgen-Abfragefunktionen verwenden:

Dataverse ServiceClient verwenden

Verwenden Sie für .NET Anwendungen Dataverse.Client.ServiceClient.DiscoverOnlineOrganizationsAsync-Methode zum Aufrufen der Global Discovery Services.

 // 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 sie im discoveryServiceUri Parameter übergeben wird, werden keine Daten im Shape einer Instanz zurückgegeben. Sie gibt Daten als DiscoverOrganizationsResult-Klasse zurück, die eine OrganizationDetailCollection-Eigenschaft enthält, die eine Auflistung von OrganizationDetail-Klasseninstanzen enthält. Diese Klasse enthält die gleichen Informationen wie die Instance-Typen, die vom OData-Service zurückgegeben werden.

CrmServiceClient verwenden

Verwenden Sie für .NET Framework-Anwendungen weiterhin die CrmServiceClient.DiscoverGlobalOrganizations-Methode, um den Global Discovery Service aufzurufen.

  // 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 bei der ServiceClient.DiscoverOnlineOrganizationsAsync Methode gibt die CrmServiceClient.DiscoverGlobalOrganizations Methode auch keine Daten als Instanz zurück. Sie gibt eine OrganizationDetailCollection zurück, die eine Auflistung von OrganizationDetail-Klasseninstanzen enthält. Diese Sammlung enthält dieselben Informationen wie die Typen, die vom OData-Dienst zurückgegeben werden Instance.

Siehe auch

Beispiel: Beispiel für globalen Suchdienst (C#)
Beispiel: Zugreifen auf den Suchdienst mit CrmServiceClient
Beispiel: Blazor WebAssembly mit globaler Suche