Referência da API REST do Serviço de Descoberta
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:
- A qual nuvem o usuário pertence
- Onde o aplicativo pode enviar o usuário para efetuar login
- 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 |