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

  • Article

S’applique à : Office 365

Notes

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. Pour plus d’informations, consultez notre annonce.

Utilisation du service Découverte Office 365

Pour interagir avec l’API du service Découverte, envoyez des requêtes 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.

Notes

Le service Découverte fournit uniquement des fonctionnalités pour l’environnement Office 365 Online 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écouverte Description
https://api.office.com/discovery/v1.0/me Prend en charge un seul point de terminaison API par service pour la version publiée des API Office 365.

Renvoie OData v4 (https://www.odata.org/documentation/odata-version-4-0/) par défaut.
https://api.office.com/discovery/v2.0/me Prend en charge plusieurs points de terminaison API par service pour la version publiée des API Office 365.

Renvoie OData v4 (https://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. Elle renvoie les points de terminaison nécessaires pour poursuivre le Service de découverte. Elle est utilisée la première fois qu’un utilisateur essaie votre application.

Elle indique à votre application :

  1. À quel cloud appartient l’utilisateur
  2. Où l’application peut envoyer l’utilisateur pour qu'il se connecte
  3. Où aller pour obtenir un jeton

Paramètre Type Description
scope chaîne Une 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_uri chaîne URI vers laquelle rediriger après la fin de l’autorisation.

Exemple : https://contoso.com/continue
lcid chaîne Facultatif. 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éponse Description
302 Found Le corps de la réponse contient des valeurs concernant l’application et l’utilisateur

Élément de corps de réponse Description
Localisation : redirect_URI URI 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. Elle doit être transmise au service de jeton dans le cadre de la demande de jeton pour le service de découverte.

Notes

Toutes ces informations sont statiques pour ce compte d’utilisateur. Par conséquent, les clients doivent les mettre en cache puis les réutiliser pour éviter d'agacer 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.


Headers Description
Authorization Un jeton d’accès obtenu pendant la phase d’autorisation.

Exemple : Authorization: BEARER 2YotnFZFEjr1zCsicMWpAA...
Accept Facultatif. 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, la valeur par défaut est Atom.

Exemple : Accept: application/json;odata=verbose

Paramètres Type Description
$select chaîne Facultatif. 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. Voir https://www.odata.org/docs/.

Exemple : Capability,ServiceUri
$filter chaîne Facultatif. 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 https://www.odata.org sous l’onglet Documentation pour les fonctions de prédicat disponibles.

Réponse Signification Description
200 OK Le 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 les fonctionnalités détectables ainsi que les services qui les implémentent. /AllServices accepte les requêtes anonymes et n'exige donc pas un jeton d’accès.


Headers Description
Accept Facultatif. 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, la valeur par défaut est Atom.

Exemple : Accept: application/json;odata=verbose

Paramètres Type Description
$select chaîne Facultatif. Liste des propriétés de l’objet séparées par des virgules. Fait que le service n'envoie que les propriétés sélectionnées. Il est utilisé pour conserver la bande passante en ne téléchargeant pas les propriétés qui ne sont pas utilisées par l’application. Voir https://www.odata.org/docs/.

Exemple : Capability,ServiceUri
$filter chaîne Facultatif. 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 https://www.odata.org sous l’onglet Documentation pour les fonctions de prédicat disponibles.

Réponse Signification Description
200 OK Le 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é Type Exemple
capability Chaîne MyFiles
serviceId Chaîne
serviceName Chaîne O365_SHAREPOINT
serviceEndpointUri Chaîne https://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceResourceId Chaîne https://contoso-my.sharepoint.com

Voir aussi