Referência da API REST do Serviço de Descoberta

  • Artigo

Aplica-se ao: Office 365

Observação

O serviço de descoberta do Office 365 e o SDK para .NET estão sendo suspensos a partir de10 de janeiro de 2018, e será totalmente desativado em 1º de novembro de 2019. Comece a usar o Microsoft Graph para acessar dados do Office 365 em um único ponto de extremidade. Para obter mais detalhes, consulte nosso comunicado.

Use o serviço de descoberta do Office 365

Para interagir com a API do Serviço de Descoberta, você envia solicitações HTTP e OData. O Serviço de Descoberta suporta a descoberta de Calendário, Contatos, Email, MyFiles (para pontos de extremidade de serviço do OneDrive e OneDrive for Business), Notas (para o OneNote) e RootSite (para o SharePoint).

A identificação do recurso para o Serviço de Descoberta: ResourceId = https://api.office.com/discovery/.

Para exemplos de código sobre como usar a API do Serviço de Descoberta e encontrar pontos de extremidade para serviços que você acessa usando as APIs do Office 365, veja APIs do Office 365: como usar o Serviço de Descoberta e Exemplo do Serviço de Descoberta do Office 365.

Observação

O Serviço de Descoberta funciona apenas no ambiente on-line do Office 365 e não funciona em implantações locais.

Controle de versão

A seguir estão as versões do Serviço de Descoberta.


Ponto de extremidade da API do serviço de descoberta Descrição
https://api.office.com/discovery/v1.0/me Suporta um único ponto de extremidade da API por serviço para a versão lançada das APIs do Office 365.

Retorna OData v4 (https://www.odata.org/documentation/odata-version-4-0/) por padrão.
https://api.office.com/discovery/v2.0/me Suporta vários pontos de extremidade da API por serviço para a versão lançada das APIs do Office 365.

Retorna OData v4 (https://www.odata.org/documentation/odata-version-4-0/) por padrão.

Operações do Serviço de Descoberta

Conexão inicial

Isso leva o cliente a uma página da web na qual o usuário insere as informações da conta. Ele retorna os pontos de extremidade necessários para continuar com o Serviço de Descoberta. Isso é usado da primeira vez que um usuário experimenta seu aplicativo.

Indica ao aplicativo:

  1. A qual nuvem o usuário pertence
  2. Onde o aplicativo pode enviar o usuário para efetuar login
  3. Onde ir para obter um token

Parâmetro Tipo Descrição
scope sequência de caracteres Uma lista delimitada por espaço de tokens capability.operation. Este escopo está nos termos do Office 365.

Exemplo: MyFiles.Write ou Mail.Read
redirect_uri sequência de caracteres URI para redirecionar após a autorização ser concluída.

Exemplo: https://contoso.com/continue
lcid sequência de caracteres Opcional. Um LCID decimal para localizar a interface do usuário do Email HRD.

Exemplo: 1031

Nota Esta API intencionalmente não aceita o email do usuário porque isso pode comprometer a privacidade do usuário, enviando o email do usuário para fora do domínio atual.

Resposta Descrição
302 Encontrado O corpo da resposta contém valores sobre o aplicativo e o usuário

Item do corpo da resposta Descrição
Localização: redirect_URI URI para redirecionar após a autorização ser concluída.
?user_email=... O endereço de email que o usuário inseriu.
&account_type=... 1 - Conta da Microsoft (Live)
2 - Conta organizacional (Office 365)
&authorization_service=... URL do endpoint em que o cliente pode obter um código de autorização.
&token_service=... URL do ponto de extremidade em que o cliente pode trocar um código de autorização para um token de acesso e um token de atualização.
&scope=... O escopo original traduzido para o domínio de destino. Os clientes só precisam conhecer os termos do escopo do Office 365. Se a região de destino for Live, o escopo original do Office 365 será traduzido em termos dinâmicos.
&unsupported_scope=... Se houver itens de escopo que não podem ser traduzidos, eles serão compilados em unsupported_scope sem uma alteração. Isso é necessário porque cada serviço de autorização entende o escopo somente em seus próprios termos. Como o serviço de autorização do Office 365 não aceita um parâmetro de escopo, tanto scope quanto unsupported_scope são retornados em branco.
&discovery_service=... URL do ponto de extremidade em que o cliente pode descobrir serviços de destino.
&discovery_resource=... Identificação de recursos do Serviço de Descoberta. Deve ser passado para o serviço de token como parte da solicitação de token para o Serviço de Descoberta.

Observação

Todas essas informações são estáticas para essa conta de usuário. Portanto, os clientes devem armazená-las em cache e, em seguida, reutilizá-las para evitar incomodar o usuário com interface do usuário desnecessária.

Exemplo

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 serviços específicos

Use a API /Services para obter o ponto de extremidade de um serviço específico.


Cabeçalhos Descrição
Authorization Um token de acesso obtido durante a fase de autorização.

Exemplo: Autorização: BEARER 2YotnFZFEjr1zCsicMWpAA...
Accept Opcional. Este cabeçalho controla o formato do conteúdo da resposta:
Para Atom: application/atom+xml

Para JSON: application/json;odata=verbose

Se este cabeçalho for omitido, o padrão será Atom.

Exemplo: Accept: application/json;odata=verbose

Parâmetros Tipo Descrição
$select sequência de caracteres Opcional. Uma lista separada por vírgula de propriedades do objeto. Faz com que o serviço projete somente as propriedades selecionadas. Usado para economizar largura de banda ao não baixar propriedades que não são usadas pelo aplicativo. Confira https://www.odata.org/docs/.

Exemplo: Capability,ServiceUri
$filter sequência de caracteres Opcional. Um predicado OData que filtra o conjunto de resultados original. Usado para economizar largura de banda ao não baixar instâncias de objetos que não são usadas pelo aplicativo. Confira https://www.odata.org na guia Documentação para ver as funções de predicado disponíveis.

Resposta Significado Descrição
200 OK O corpo da resposta contém uma lista de entradas projetadas, filtradas e codificadas do schema ServiceInfo de acordo com a solicitação OData. Confira a definição do esquema ServiceInfo schema.

Exemplo

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;

Saiba quais serviços podem ser descobertos

Use a API /Allservices para aprender todos os recursos detectáveis ​​junto com os serviços que os implementam. /AllServices aceita solicitações anônimas e, portanto, não requer um token de acesso.


Cabeçalhos Descrição
Accept Opcional. Este cabeçalho controla o formato do conteúdo da resposta:
Para Atom: application/atom+xml

Para JSON: application/json;odata=verbose

Se este cabeçalho for omitido, o padrão será Atom.

Exemplo: Accept: application/json;odata=verbose

Parâmetros Tipo Descrição
$select sequência de caracteres Opcional. Uma lista separada por vírgula de propriedades do objeto. Faz com que o serviço projete somente as propriedades selecionadas. Usado para economizar largura de banda ao não baixar propriedades que não são usadas pelo aplicativo. Confira https://www.odata.org/docs/.

Exemplo: Capability,ServiceUri
$filter sequência de caracteres Opcional. Um predicado OData que filtra o conjunto de resultados original. Usado para economizar largura de banda ao não baixar instâncias de objetos que não são usadas pelo aplicativo. Confira https://www.odata.org na guia Documentação para ver as funções de predicado disponíveis.

Resposta Significado Descrição
200 OK O corpo da resposta contém uma lista de entradas projetadas, filtradas e codificadas do schema ServiceInfo de acordo com a solicitação OData. Confira a definição do esquema ServiceInfo schema.

Exemplo

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

As APIs /services API e /allservices API usam entradas do ServiceInfo no corpo de resposta.


Propriedade Tipo Exemplo
capacidade Sequência de caracteres MyFiles
serviceId Sequência de caracteres
serviceName Sequência de caracteres O365_SHAREPOINT
serviceEndpointUri Sequência de caracteres https://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceResourceId Sequência de caracteres https://contoso-my.sharepoint.com

Confira também