Table of contents
TOC
Réduire la table des matières
Développer la table des matières
Dernière mise à jour: 29/06/2018

Référence de l’API REST du service de découverte

Concerne : Office 365

Utilisation de service de découverte Office 365

Le service de découverte Office 365 et le SDK pour .NET seront obsolètes début 10 janvier 2018, et seront complètement désactivés le 1er novembre 2019. Commencer à utiliser Microsoft Graph pour accéder aux données Office 365 par un seul point de terminaison. Voir plus de détails dans notre annonce.

Pour interagir avec l’API du service découverte, envoyez des demandes HTTP et OData. Le service de découverte permet de trouver les Calendriers, Contacts, Courriers, MesFichiers (pour les points de terminaison OneDrive et OneDrive Entreprise), Notes (pour OneNote), et SiteRacine (pour SharePoint).

ID de ressource pour le service de découverte : ResourceId = https://api.office.com/discovery/.

Pour obtenir des exemples de code sur l’utilisation de l’API de découverte de service pour rechercher des points de terminaison pour les services auxquels vous accédez à l’aide des API Office 365, consultez API Office 365 : Comment utiliser le service de découverte et Exemple de service de découverte Office 365.

Remarque Le service de découverte fournit uniquement des fonctionnalités pour l’environnement en ligne Office 365 et ne fonctionne pas pour les déploiements locaux.

Contrôle de version

Voici les versions du service de découverte.

Point de terminaison de l’API du service de découverteDescription
https://api.office.com/discovery/v1.0/mePrend en charge un seul point de terminaison API par service pour la version publiée des API Office 365.
Renvoie OData v4 (http://www.odata.org/documentation/odata-version-4-0/) par défaut.
https://api.office.com/discovery/v2.0/mePrend en charge plusieurs points de terminaison API par service pour la version publiée des API Office 365.
Renvoie OData v4 (http://www.odata.org/documentation/odata-version-4-0/) par défaut.

Opérations du service de découverte

Connexion initiale

Amène le client à une page Web où l’utilisateur entre les informations de compte. Renvoie les points de terminaison nécessaires pour continuer avec le service de découverte. Utilisé la première fois qu’un utilisateur essaie votre application. Indique à votre application :

  1. à quel cloud appartient à l’utilisateur
  2. où l’application peut envoyer l’utilisateur pour se connecter
  3. où aller pour obtenir un jeton

ParamètreTypeDescription
scopechaîneUne liste délimitée par des espaces de jetons capability.operation. Cette étendue est dans les conditions d’Office 365.
Exemple : MyFiles.Write ou Mail.Read
redirect_urichaîneURI vers laquelle rediriger après la fin de l’autorisation.
Exemple : https://contoso.com/continue
lcidchaîneFacultative. Un LCID décimal pour localiser l’interface utilisateur HRD de l’e-mail.
Exemple : 1031

Remarque Volontairement, cette API n’accepte pas l’e-mail de l’utilisateur, car cela pourrait compromettre la confidentialité de l’utilisateur en envoyant son e-mail hors du domaine en cours.
RéponseDescription
302 FoundLe corps de la réponse contient des valeurs concernant l’application et l’utilisateur
Élément de corps de réponseDescription
Localisation : redirect_URIURI vers laquelle rediriger après la fin de l’autorisation.
?user_email=...Adresse e-mail que l’utilisateur a saisie.
&account_type=...1 - Compte Microsoft (Live)
2 - Compte organisationnel (Office 365)
&authorization_service=...URL du point de terminaison où le client peut obtenir un code d’autorisation.
&token_service=...URL du point de terminaison où le client peut échanger un code d’autorisation pour un jeton d’accès et un jeton d’actualisation.
&scope=...L’étendue d’origine traduite pour le domaine cible. Les clients ont uniquement besoin de connaître les conditions d’étendue d’Office 365. Si le domaine cible est Live, l’étendue Office 365 d’origine est traduite en conditions Live.
&unsupported_scope=...S’il existe des éléments d’étendue qui ne peuvent pas être traduits, ils sont compilés dans unsupported_scope sans modification. Ceci est nécessaire car chaque service d’autorisation ne comprend la portée que dans ses propres conditions. Comme que le service d’autorisation Office 365 n’accepte pas de paramètre d’étendue, à la fois « scope » et « unsupported_scope » sont renvoyés vides.
&discovery_service=...URL du point de terminaison où le client peut découvrir les services cibles.
&discovery_resource=...Identification de ressource du service de découverte. Doit être transmis au service de jeton dans le cadre de la demande de jeton pour le service de découverte.

Remarque Toutes ces informations sont statiques pour ce compte d’utilisateur. Par conséquent, les clients doivent le mettre en cache, puis le réutiliser pour éviter de gêner l’utilisateur avec une interface utilisateur inutile.

Exemple :

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(...);
}

Découvrir des services spécifiques

Utilisez l’API /Services pour obtenir le point de terminaison d’un service spécifique.


En-têtesDescription
AuthorizationUn jeton d’accès obtenu pendant la phase d’autorisation.
Exemple : Authorization: BEARER 2YotnFZFEjr1zCsicMWpAA...
AcceptFacultatif. Cet en-tête contrôle le format de la charge utile de réponse :
Pour Atom : application/atom+xml

Pour JSON : application/json;odata=verbose

Si cet en-tête est omis, l’en-tête par défaut est celui pour Atom.

Exemple : Accept: application/json;odata=verbose
ParamètresTypeDescription
$selectchaîneFacultative. Une liste de propriétés d’objets séparées par des virgules. Le service à projète uniquement les propriétés sélectionnées. Utilisé pour préserver la bande passante en ne téléchargeant pas les propriétés qui ne sont pas utilisées par l’application. Consultez l’article http://www.odata.org/docs/.
Exemple : Capability,ServiceUri
$filterchaîneFacultative. Prédicat OData qui filtre le jeu de résultats d’origine. Utilisé pour préserver la bande passante en ne téléchargeant pas les instances d’objets qui ne sont pas utilisées par l’application. Voir http://www.odata.org sous l’onglet Documentation pour les fonctions de prédicat disponibles.
RéponseSignificationDescription
200OKLe corps de la réponse contient une liste d’entrées ServiceInfo schema projetées, filtrées et codées en fonction de la demande OData. Voir la définition du schéma ServiceInfo schema.

Exemple :

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;

Découvrir quels services sont détectables

Utilisez l’API /allservices pour découvrir toutes les capacités détectables avec les services qui les implémentent. /AllServices accepte les demandes anonymes et ne nécessite donc pas de jeton d’accès.


En-têtesDescription
AcceptFacultative. Cet en-tête contrôle le format de la charge utile de réponse :
Pour Atom : application/atom+xml

Pour JSON : application/json;odata=verbose

Si cet en-tête est omis, l’en-tête par défaut est celui pour Atom.

Exemple : Accept: application/json;odata=verbose
ParamètresTypeDescription
$selectchaîneFacultative. Une liste de propriétés d’objets séparées par des virgules. Le service à projète uniquement les propriétés sélectionnées. Utilisé pour préserver la bande passante en ne téléchargeant pas les propriétés qui ne sont pas utilisées par l’application. Consultez l’article http://www.odata.org/docs/. Exemple : Capability,ServiceUri
$filterchaîneFacultative. Prédicat OData qui filtre le jeu de résultats d’origine. Utilisé pour préserver la bande passante en ne téléchargeant pas les instances d’objets qui ne sont pas utilisées par l’application. Voir http://www.odata.org sous l’onglet Documentation pour les fonctions de prédicat disponibles.
RéponseSignificationDescription
200OKLe corps de la réponse contient une liste d’entrées ServiceInfo schema projetées, filtrées et codées en fonction de la demande OData. Voir la définition du schéma ServiceInfo schema.

Exemple :

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;

Schéma ServiceInfo

L’API /services et l’API /allservices utilisent les entrées ServiceInfo dans leur corps de réponse.


PropriétéTypeExemple
capabilityChaîneMyFiles
serviceIdChaîne
serviceNameChaîneO365_SHAREPOINT
serviceEndpointUriChaînehttps://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceResourceIdChaînehttps://contoso-my.sharepoint.com

Ressources supplémentaires

© 2018 Microsoft