Ссылка на REST API службы обнаружения

Область применения: Office 365

Примечание

Служба обнаружения Office 365 и SDK для .NET устарели 10 января 2018 года и будут полностью списаны 1 ноября 2019 года. Начните использовать Microsoft Graph для доступа к данным Office 365 в одной конечной точке. Для получения дополнительных сведений см. наше объявление.

Использование службы обнаружения Office 365

Чтобы взаимодействовать с API службы обнаружения, вы отправляете запросы HTTP и OData. Служба обнаружения поддерживает обнаружение Календаря, Контактов, Почты, MyFiles (для конечных точек обслуживания OneDrive и OneDrive для бизнеса), Заметок (для OneNote) и RootSite (для SharePoint).

ИД ресурса для службы обнаружения: ResourceId = https://api.office.com/discovery/.

Для примеров кода того, как использовать API службы обнаружения для поиска конечных точек для служб, к которым вы обращаетесь с использованием API Office 365, см. API Office 365: использование службы обнаружения и Пример службы обнаружения Office 365.

Примечание

Служба обнаружения предоставляет только функциональные возможности для онлайн-среды Office 365 и не работает для локальных развертываний.

Управление версиями

Ниже приведены версии службы обнаружения.


Конечная точка API службы обнаружения Описание
https://api.office.com/discovery/v1.0/me Поддерживает единую конечную точку API на службу для выпущенной версии API Office 365.

Возвращает OData v4 (http://www.odata.org/documentation/odata-version-4-0/) по умолчанию.
https://api.office.com/discovery/v2.0/me Поддерживает несколько конечных точек API на службу для выпущенной версии API Office 365.

Возвращает OData v4 (http://www.odata.org/documentation/odata-version-4-0/) по умолчанию.

Операции службы обнаружения

Первоначальный вход в систему

Это приводит клиента к веб-странице, где пользователь вводит данные учетной записи. Она возвращает конечные точки, необходимые для продолжения работы со службой обнаружения. Это используется при первом запуске приложения пользователем.

Он сообщает вашему приложению:

  1. К какому облаку принадлежит пользователь
  2. Куда приложение может отправить пользователя для входа в систему
  3. Где можно получить маркер

Параметр Тип Описание
scope строка Разделенный пробелами список маркеров capability.operation. Эта область находится в терминах Office 365.

Пример: MyFiles.Write или Mail.Read
redirect_uri строка URI для перенаправления после авторизации завершен.

Пример: https://contoso.com/continue
lcid строка Необязательный. Десятичный идентификатор LCID для локализации пользовательского интерфейса HRD электронной почты.

Пример: 1031

Примечание. Этот API намеренно не принимает почту пользователя, поскольку это может нарушить конфиденциальность пользователя, отправив почту пользователя из текущего домена.

Ответ Описание
302 Найдено Текст ответа содержит значения по приложению и пользователю

Элемент текста ответа Описание
Расположение: redirect_URI URI для перенаправления после авторизации завершен.
?user_email=... Адрес почты, введенный пользователем.
&account_type=... 1 - учетная запись Microsoft (Live)
2 - учетная запись в организации (Office 365)
&служба_авторизации=... URL конечной точки, где клиент может получить код авторизации.
&служба_маркера=... URL конечной точки, где клиент может обменять код авторизации для маркера доступа и маркера обновления.
&scope=... Исходная область, переведенная для целевой области. Клиентам необходимо знать только термины области Office 365. Если целевой областью является Live, исходная область Office 365 преобразуется в термины Live.
&unsupported_scope=... Если есть объекты области, которые невозможно перевести, они компилируются в unsupported_scope без изменения. Это необходимо, потому что каждая служба авторизации понимает область действия только для своих собственных терминов. Поскольку служба авторизации Office 365 не принимает параметр области, область и unsupported_scope возвращаются пустыми.
&discovery_service=... URL конечной точки, где клиент может обнаружить целевые службы.
&discovery_resource=... Идентификатор ресурса службы обнаружения. Он должен быть передан в службу маркеров как часть запроса маркера для службы обнаружения.

Примечание

Вся эта информация является статической для этой учетной записи пользователя. Поэтому клиенты должны кэшировать ее, а затем повторно использовать, чтобы не раздражать пользователя ненужным пользовательским интерфейсом.

Пример

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(...);
}

Узнайте о конкретных службах

Используйте /службы API для получения конечной точки конкретной службы.


Заголовки Описание
Authorization Маркер доступа, полученный на этапе авторизации.

Пример: Authorization: BEARER 2YotnFZFEjr1zCsicMWpAA...
Accept Необязательный. Этот заголовок управляет форматом полезных данных ответа:
Для Atom: application/atom+xml

Для JSON: application/json;odata=verbose

Если этот заголовок пропущен, по умолчанию используется Atom.

Пример: Accept: application/json;odata=verbose

Параметры Тип Описание
$select строка Необязательный. Список свойств объектов, разделенный запятыми. Заставляет службу проецировать только выбранные свойства. Он используется для экономии полосы пропускания, не загружая свойства, которые не используются приложением. См. http://www.odata.org/docs/.

Пример: Возможность, ServiceUri
$filter строка Необязательный. Предикат OData, который фильтрует исходное множество результатов. Он используется для экономии полосы пропускания, не загружая экземпляры объектов, которые не используются приложением. Для доступных функций предиката см. http://www.odata.org под вкладкой «Документация».

Ответ Значение Описание
200 OK Текст ответа содержит список записей Схема ServiceInfo, которые прогнозированы, отфильтрованы и закодированы в соответствии с запросом OData. См. определение схемы в Схема ServiceInfo.

Пример

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;

Узнайте, какие службы можно обнаружить

Используйте AllServices API, чтобы узнать о всех возможностях, доступных для обнаружения, а также службах, которые их реализуют. /AllServices принимает анонимные запросы и, следовательно, не требует маркера доступа.


Заголовки Описание
Accept Необязательный. Этот заголовок управляет форматом полезных данных ответа:
Для Atom: application/atom+xml

Для JSON: application/json;odata=verbose

Если этот заголовок пропущен, по умолчанию используется Atom.

Пример: Accept: application/json;odata=verbose

Параметры Тип Описание
$select строка Необязательный. Список свойств объектов, разделенный запятыми. Заставляет службу проецировать только выбранные свойства. Он используется для экономии полосы пропускания, не загружая свойства, которые не используются приложением. См. http://www.odata.org/docs/.

Пример: Возможность, ServiceUri
$filter строка Необязательный. Предикат OData, который фильтрует исходное множество результатов. Он используется для экономии полосы пропускания, не загружая экземпляры объектов, которые не используются приложением. Для доступных функций предиката см. http://www.odata.org под вкладкой «Документация».

Ответ Значение Описание
200 OK Текст ответа содержит список записей Схема ServiceInfo, которые прогнозированы, отфильтрованы и закодированы в соответствии с запросом OData. См. определение схемы в Схема ServiceInfo.

Пример

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

API-интерфейсы /services API и /allservices API используют записи ServiceInfo в своем тексте ответа.


Свойство Тип Пример
возможность Строка MyFiles
serviceId Строка
serviceName Строка O365_SHAREPOINT
serviceEndpointUri Строка https://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceResourceId Строка https://contoso-my.sharepoint.com

См. также