Referencia del Servicio de detección de API REST
Se aplica a: Office 365
Nota
El servicio de detección de Office 365 y el SDK para .NET estará en desuso desde el 10 de enero de 2018, y será completamente desactivado el 1 de noviembre de 2019. Empiece a usar Microsoft Graph para acceder a los datos de Office 365 en un punto de conexión único. Para obtener más detalles, consulte nuestro anuncio.
Use el servicio de detección de Office 365
Para interactuar con la API del servicio Discovery, envíe solicitudes HTTP y OData. El Servicio de detección admite detección de Calendario, Contactos, Correo, Mis archivos (para puntos de conexión de Servicios de negocios OneDrive y OneDrive), Notas (para OneNote) y SitioRaíz (para SharePoint).
El ID de recurso para el Servicio de detección:ResourceId = https://api.office.com/discovery/.
Para ejemplos de código sobre cómo usar la API del Servicio de detección para buscar puntos de conexión para los servicios a los que accede utilizando las API de Office 365, consulte API de Office 365: cómo usar el Servicio de detección y Ejemplo del Servicio de detección de Office 365.
Nota
El Servicio de detección solo proporciona funcionalidad para el entorno en línea de Office 365 y no funciona para implementaciones locales.
Control de versiones
Las siguientes son las versiones del Servicio de detección.
| Punto de conexión de la API de servicio de detección | Descripción |
|---|---|
| https://api.office.com/discovery/v1.0/me | Admite un solo punto de conexión de API por servicio para la versión lanzada de las API de Office 365. Devuelve OData v4 (https://www.odata.org/documentation/odata-version-4-0/) por defecto. |
| https://api.office.com/discovery/v2.0/me | Admite múltiples puntos de conexión de API por servicio para la versión lanzada de las API de Office 365. Devuelve OData v4 (https://www.odata.org/documentation/odata-version-4-0/) por defecto. |
Operaciones del servicio de detección
Inicio de sesión inicial
Esto lleva al cliente a una página web donde el usuario ingresa la información de la cuenta. Devuelve los puntos de conexión necesarios para continuar con Servicio de Detección. Esto se usa la primera vez que un usuario prueba su aplicación.
Le dice a su aplicación:
- A qué nube pertenece el usuario
- Dónde puede la aplicación enviar al usuario para iniciar sesión
- Dónde ir para obtener un token
| Parámetro | Tipo | Descripción |
|---|---|---|
scope |
cadena | Una lista delimitada por espacios de capacidad.operación tokens. Este ámbito está en términos de Office 365. Ejemplo: Misarchivos.Escribir o Correo.Leer |
redirect_uri |
cadena | URI para redirigir a después de que se completa la autorización. Ejemplo: https://contoso.com/continue |
lcid |
cadena | Opcional. Un LCID decimal para localizar la interfaz de usuario de correo electrónico HRD. Ejemplo:1031 Nota Esta API no acepta el correo electrónico del usuario deliberadamente porque podría comprometer la privacidad del usuario al enviar el correo electrónico del usuario fuera del dominio actual. |
| Respuesta | Descripción |
|---|---|
302 Encontrado |
El cuerpo de respuesta contiene valores sobre la aplicación y el usuario |
| Elemento del cuerpo de respuesta | Descripción |
|---|---|
| Ubicación: redirigir_URI | URI para redirigir a después de que se completa la autorización. |
| ?user_email=... | La dirección de correo electrónico que ingresó el usuario. |
| &tipo_cuenta=... | 1 - Cuenta de Microsoft (Activa) 2 - Cuenta de organización (Office 365) |
| &serviciode_autorización=... | Punto de conexión URL donde el cliente puede obtener un código de autorización. |
| &servicio_token=... | Punto de conexión URL donde el cliente puede intercambiar un código de autorización para un token de acceso y un token de actualización. |
| &ámbito=... | El ámbito original traducido para el dominio de destino. Los clientes solo necesitan conocer los términos del ámbito de Office 365. Si el dominio de destino está Activo, el ámbito original de Office 365 se traduce a términos Activos. |
| &unsupported_scope =... | Si hay elementos de ámbito que no se pueden traducir, se compilan en unsupported_scope sin cambios. Esto es necesario porque cada servicio de autorización entiende el ámbito solo en sus propios términos. Dado que el servicio de autorizaciones de Office 365 no acepta un parámetro de ámbito, tanto el ámbito como el ámbito no compatible se devuelven vacíos. |
| &servicio_detección=... | Punto de conexión URL donde el cliente puede detectar servicios de destino. |
| &recurso_detección=... | Identificación de recursos del Servicio de Detección. Se debe pasar al servicio de token como parte de la solicitud de token para el Servicio de Detección. |
Nota
Toda esta información es estática para esta cuenta de usuario. Por lo tanto, los clientes deben almacenarlo en la memoria caché y luego reutilizarlo para evitar molestar al usuario con una IU innecesaria.
Ejemplo
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(...);
}
Descubra servicios específicos
Utilice el / Servicios API para obtener el punto de conexión de un servicio específico.
| Encabezados | Descripción |
|---|---|
Authorization |
Un token de acceso obtenido durante la fase de Autorización. Ejemplo: Autorización: BEARER 2YotnFZFEjr1zCsicMWpAA... |
Accept |
Opcional. Este encabezado controla el formato de la carga de respuesta: Para Atom: application / atom + xml Para JSON: application / json; odata = verbose Si se omite este encabezado, el valor predeterminado es Atom. Ejemplo: Aceptar: application / json; odata = verbose |
| Parámetros | Tipo | Descripción |
|---|---|---|
$select |
cadena | Opcional. Una lista de propiedades de objetos separadas por comas. Hace que el servicio proyecte solo las propiedades seleccionadas. Se usa para conservar el ancho de banda al no descargar propiedades que la aplicación no usa. Consulte https://www.odata.org/docs/. Ejemplo: Capacidad, ServicioUri |
$filter |
cadena | Opcional. Un predicado OData que filtra el conjunto de resultados original. Se usa para conservar el ancho de banda al no descargar propiedades que la aplicación no usa. Ver https://www.odata.org en la pestaña Documentación para funciones de predicado disponibles. |
| Respuesta | Significado | Descripción |
|---|---|---|
200 |
Aceptar | El cuerpo de respuesta contiene una lista de Esquema de ServiceInfo entradas proyectadas, filtradas y codificadas de acuerdo con la solicitud OData. Ver la definición de Esquema de ServiceInfo esquema. |
Ejemplo
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;
Conozca qué servicios son detectables
Utilizce el API/AllServices para aprender todas las capacidades detectables junto con los servicios que las implementan. /Todos los servicios acepta solicitudes anónimas y, por lo tanto, no requiere un token de acceso.
| Encabezados | Descripción |
|---|---|
Accept |
Opcional. Este encabezado controla el formato de la carga de respuesta: Para Atom: application / atom + xml Para JSON: application / json; odata = verbose Si se omite este encabezado, el valor predeterminado es Atom. Ejemplo: Aceptar: application / json; odata = verbose |
| Parámetros | Tipo | Descripción |
|---|---|---|
$select |
cadena | Opcional. Una lista de propiedades de objetos separadas por comas. Hace que el servicio proyecte solo las propiedades seleccionadas. Se usa para conservar el ancho de banda al no descargar propiedades que la aplicación no usa. Consulte https://www.odata.org/docs/. Ejemplo: Capacidad, ServicioUri |
$filter |
cadena | Opcional. Un predicado OData que filtra el conjunto de resultados original. Se usa para conservar el ancho de banda al no descargar propiedades que la aplicación no usa. Ver https://www.odata.org en la pestaña Documentación para funciones de predicado disponibles. |
| Respuesta | Significado | Descripción |
|---|---|---|
200 |
Aceptar | El cuerpo de respuesta contiene una lista de Esquema de ServiceInfo entradas proyectadas, filtradas y codificadas de acuerdo con la solicitud OData. Ver la definición de Esquema de ServiceInfo esquema. |
Ejemplo
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;
Esquema de ServiceInfo
Las APIS /servicios API y / allservices API usan entradas de ServiceInfo en su cuerpo de respuesta.
| Propiedad | Tipo | Ejemplo |
|---|---|---|
| operativa | Cadena | Mis archivos |
| serviceId | Cadena | |
| serviceName | Cadena | O365_SHAREPOINT |
| punto de conexión de servicio Uri | Cadena | https://contoso-my.sharepoint.com/personal/alexd_contoso_com |
| serviceResourceId | Cadena | https://contoso-my.sharepoint.com |