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

Статья
06/05/2018

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

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

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

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

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

Параметр	Тип	Описание
`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`	строка	Необязательный. Список свойств объектов, разделенный запятыми. Заставляет службу проецировать только выбранные свойства. Он используется для экономии полосы пропускания, не загружая свойства, которые не используются приложением. См. https://www.odata.org/docs/. Пример: Возможность, ServiceUri
`$filter`	строка	Необязательный. Предикат OData, который фильтрует исходное множество результатов. Он используется для экономии полосы пропускания, не загружая экземпляры объектов, которые не используются приложением. Для доступных функций предиката см. https://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`	строка	Необязательный. Список свойств объектов, разделенный запятыми. Заставляет службу проецировать только выбранные свойства. Он используется для экономии полосы пропускания, не загружая свойства, которые не используются приложением. См. https://www.odata.org/docs/. Пример: Возможность, ServiceUri
`$filter`	строка	Необязательный. Предикат OData, который фильтрует исходное множество результатов. Он используется для экономии полосы пропускания, не загружая экземпляры объектов, которые не используются приложением. Для доступных функций предиката см. https://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

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

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

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

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

Пример

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

Пример

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

Пример

Схема ServiceInfo

См. также

Дополнительные ресурсы

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

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

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

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

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

Пример

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

Пример

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

Пример

Схема ServiceInfo

См. также

Дополнительные ресурсы