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 (http://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 (http://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:

  1. A qué nube pertenece el usuario
  2. Dónde puede la aplicación enviar al usuario para iniciar sesión
  3. 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 http://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 http://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 http://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 http://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

Vea también