Discovery Service REST API Referenz

  • Artikel

Gilt für: Office 365

Hinweis

Der Office 365 Discovery Service und das SDK für .NET sind ab dem 10. Januar 2018 veraltet und werden am 1. November 2019 vollständig außer Betrieb genommen. Verwenden Sie Microsoft Graph, um auf Office 365-Daten in einem einzigen Endpunkt zuzugreifen. Weitere Informationen finden Sie in unserer Ankündigung.

Nutzen Sie den Office 365 Discovery Service

Um mit der Discovery Service API zu interagieren, senden Sie HTTP- und OData-Anfragen. Der Ermittlungsdienst unterstützt das Entdecken von Kalender, Kontakte, Mail, MyFiles (für OneDrive und OneDrive für Business Dienst-Endpunkte), Notes (für OneNote) und RootSite (für SharePoint).

Die Ressourcen-ID für den Ermittlungsdienst:ResourceId = https://api.office.com/discovery/.

Code-Beispiele zur Verwendung der Ermittlungsdienst-API zum Auffinden von Endpunkten für Dienste, auf die Sie über die Office 365-APIs zugreifen, finden Sie unter Office 365-APIs: Erste Schritte mit dem Ermittlungsdienst und Office 365 Ermittlungsdienst-Beispiel.

Hinweis

Der Ermittlungsdienst bietet nur Funktionen für die Office 365-Online-Umgebungen und funktioniert nicht für lokale Anwendungen.

Versionsverwaltung

Im Folgenden finden Sie die Versionen des Discovery Service.


Discovery Service API-Endpunkt Beschreibung
https://api.office.com/discovery/v1.0/me Unterstützt einen einzigen API-Endpunkt pro Dienst für die freigegebene Version der Office 365-APIs.

Gibt OData v4 zurück (https://www.odata.org/documentation/odata-version-4-0/) standardmäßig.
https://api.office.com/discovery/v2.0/me Unterstützt mehrere API-Endpunkte pro Dienst für die freigegebene Version der Office 365-APIs.

Gibt OData v4 zurück (https://www.odata.org/documentation/odata-version-4-0/) standardmäßig.

Ermittlungsdienst-REST-Funktionen

Erste Anmeldung

Dadurch wird der Client auf eine Webseite gebracht, auf der der Benutzer Kontoinformationen eingibt. Es gibt die Endpunkte zurück, die für die Fortsetzung des Discovery Service erforderlich sind. Dies wird verwendet, wenn ein Benutzer Ihre Anwendung zum ersten Mal ausprobiert.

Es verrät Ihre Anwendung:

  1. Zu welcher Cloud der Benutzer gehört
  2. Wohin die App den Benutzer zum Einloggen schicken kann
  3. Wohin man muss, um ein Token zu bekommen

Parameter Typ Beschreibung
scope Zeichenfolge Eine durch Leerzeichen getrennte Liste von capability.operation Tokens. Dieser Bereich ist in Office 365 ausgedrückt.

Beispiel: MyFiles.Write oder Mail.Read
redirect_uri Zeichenfolge URI, auf die umgeleitet werden soll, nachdem die Autorisierung abgeschlossen ist.

Beispiel: https://contoso.com/continue
lcid Zeichenfolge Optional. Eine dezimale LCID zur Lokalisierung des Email HRD UI.

Beispiel: 1031

Note Diese API akzeptiert die Benutzer-E-Mail absichtlich nicht, da dies die Privatsphäre des Benutzers beeinträchtigen könnte, indem sie die Benutzer-E-Mail aus der aktuellen Domäne sendet.

Antwort Beschreibung
302 Found Der Antworttext enthält Werte über die App und den Benutzer.

Antworttext Beschreibung
Standort: redirect_URI URI, auf die umgeleitet werden soll, nachdem die Autorisierung abgeschlossen ist.
?user_email=... Die E-Mail-Adresse, die der Benutzer eingegeben hat.
&account_type=... 1 - Microsoft-Konto (Live)
2 - Organisationskonto (Büro 365)
&authorization_service=... Endpunkt-URL, über die der Client einen Autorisierungscode erhalten kann.
&token_service=... Endpunkt-URL, bei der der Client einen Autorisierungscode für ein Zugriffstoken und ein Refresh-Token austauschen kann.
&scope=... Der ursprüngliche Umfang für den Zielrealm. Kunden müssen nur die Bedingungen von Office 365 kennen. Wenn der Zielrealm Live ist, wird der ursprüngliche Office 365-Bereich in Live-Begriffe übersetzt.
&unsupported_scope=... Wenn es Bereiche gibt, die nicht übersetzt werden können, werden diese ohne Änderung in unsupported_scope kompiliert, da jeder Autorisierungsdienst den Bereich nur in seinen eigenen Begriffen versteht. Da der Office 365-Autorisierungsdienst keinen Scope-Parameter akzeptiert, werden sowohl scope als auch unsupported_scope leer zurückgegeben.
&discovery_service=... Endpunkt-URL, über die der Client die Zielservices ermitteln kann.
&discovery_resource=... Ressourcenidentifizierung des Discovery Service. Sie muss als Teil der Token-Anforderung für den Discovery Service an den Token-Service übergeben werden.

Hinweis

Alle diese Informationen sind statisch für dieses Benutzerkonto. Daher sollten Clients es zwischenspeichern und dann wiederverwenden, um den Benutzer nicht mit einer unnötigen Benutzeroberfläche zu belästigen.

Beispiel

var firstSignInUri = new Uri(string.Format("https://api.office.com/discovery/v1.0/me/FirstSignIn?redirect_uri={0}&scope={1}", TerminalUriText, Scope));
var terminalUri = new Uri(TerminalUriText);

//Starting authorization
var webAuthResult = await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.None, firstSignInUri, terminalUri)
   .AsTask().ConfigureAwait(continueOnCapturedContext: true);

//Authorization finished
If (webAuthResult.ResponseStatus == WebAuthenticationStatus.Success)
{
var userEmail = MyExtractParamter("user_email",webAuthResult.ResponseData);
var accountType = MyExtractParamter("account_type",webAuthResult.ResponseData);
var authorizationService = MyExtractParamter("authorization_service",webAuthResult.ResponseData);
var tokenService = MyExtractParamter("token_service", webAuthResult.ResponseData);
var discoveryService = MyExtractParamter("discovery_service", webAuthResult.ResponseData);
var scope = MyExtractParamter("scope",webAuthResult.ResponseData);
var unsupportedScope = MyExtractParamter("unsupported_scope", webAuthResult.ResponseData);

MyCacheUserInfo(...);
}

Entdecken Sie spezifische Dienstleistungen

Verwenden Sie die /Services API, um den Endpunkt eines bestimmten Dienstes zu ermitteln.


Headers Beschreibung
Authorization Ein Zugriffstoken, das während der Autorisierungsphase erhalten wurde.

Beispiel: Autorisierung: BEARER 2YotnFZFEjr1zCsicMWpAA...
Accept Optional. Dieser Header steuert das Format der Response-Payload:
Für Atom: Anwendung/atom+xml

Für JSON: application/json;odata=verbose

Wenn dieser Header weggelassen wird, ist die Voreinstellung Atom.

Beispiel: Accept: application/json;odata=verbose

Parameter Typ Beschreibung
$select Zeichenfolge Optional. Eine kommagetrennte Liste von Objekteigenschaften. Bewirkt, dass der Dienst nur die ausgewählten Eigenschaften projiziert. Es wird verwendet, um Bandbreite zu sparen, indem keine Eigenschaften heruntergeladen werden, die nicht von der Anwendung verwendet werden. Siehe https://www.odata.org/docs/.

Beispiel: Leistungsfähigkeit, ServiceUri
$filter Zeichenfolge Optional. Ein OData-Prädikat, das die ursprüngliche Ergebnismenge filtert. Es wird verwendet, um Bandbreite zu sparen, indem keine Eigenschaften heruntergeladen werden, die nicht von der Anwendung verwendet werden. Siehe https://www.odata.org unter der Registerkarte Dokumentation für die verfügbaren Prädikatfunktionen.

Antwort Bedeutung Beschreibung
200 OK Der Response-Body enthält eine Liste von ServiceInfo-Schema -Einträgen, die entsprechend der OData-Anfrage projiziert, gefiltert und kodiert werden. Siehe Definition des Schemas ServiceInfo-Schema.

Beispiel

var url = string.Format("https://api.office.com/discovery/v1.0/me/services", discoveryService);

var request = HttpWebRequest.CreateHttp(url);
request.Method = "GET";
request.Headers["Authorization"] = "Bearer " + accessToken;

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

Erfahren Sie, welche Services auffindbar sind

Verwenden Sie die /AllServices-API, um alle auffindbaren Fähigkeiten zusammen mit den Diensten, die sie implementieren, zu lernen. /AllServices akzeptiert anonyme Anfragen und benötigt daher kein Zugriffstoken.


Headers Beschreibung
Accept Optional. Dieser Header steuert das Format der Response-Payload:
Für Atom: Anwendung/atom+xml

Für JSON: application/json;odata=verbose

Wenn dieser Header weggelassen wird, ist die Voreinstellung Atom.

Beispiel: Accept: application/json;odata=verbose

Parameter Typ Beschreibung
$select Zeichenfolge Optional. Eine kommagetrennte Liste von Objekteigenschaften. Bewirkt, dass der Dienst nur die ausgewählten Eigenschaften projiziert. Es wird verwendet, um Bandbreite zu sparen, indem keine Eigenschaften heruntergeladen werden, die nicht von der Anwendung verwendet werden. Siehe https://www.odata.org/docs/.

Beispiel: Leistungsfähigkeit, ServiceUri
$filter Zeichenfolge Optional. Ein OData-Prädikat, das die ursprüngliche Ergebnismenge filtert. Es wird verwendet, um Bandbreite zu sparen, indem keine Eigenschaften heruntergeladen werden, die nicht von der Anwendung verwendet werden. Siehe https://www.odata.org unter der Registerkarte Dokumentation für die verfügbaren Prädikatfunktionen.

Antwort Bedeutung Beschreibung
200 OK Der Response-Body enthält eine Liste von ServiceInfo-Schema -Einträgen, die entsprechend der OData-Anfrage projiziert, gefiltert und kodiert werden. Siehe Definition des Schemas ServiceInfo-Schema.

Beispiel

var request = HttpWebRequest.CreateHttp("https://api.office.com/discovery/v1.0/me/services");
request.Method = "GET";
request.Headers["Accept"] = "application/json;odata=verbose";

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

ServiceInfo-Schema

Die /services API und /allservices API APIs verwenden ServiceInfo-Einträge in ihrem Antworttext.


Eigenschaft Typ Beispiel
capability Zeichenfolge MeineDateien
ServiceID Zeichenfolge
serviceName Zeichenfolge O365_SHAREPOINT
serviceEndpointUri Zeichenfolge https://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceRessourceId Zeichenfolge https://contoso-my.sharepoint.com

Siehe auch