Коды ошибок и обработка ошибок | Основные понятия API Graph
Область применения: API Graph | Azure Active Directory
Клиентские приложения, использующие API Graph Azure Active Directory (AD), должны применять логику обработки ошибок, чтобы максимально эффективно реагировать на меняющиеся условия и предоставлять наилучшее взаимодействие для своих клиентов. В этой статье рассматриваются типы ошибок, которые возвращает API Graph Azure AD, и даются общие рекомендации по их обработке.
Важно!
Для доступа к ресурсам Azure Active Directory мы настоятельно рекомендуем использовать Microsoft Graph вместо API Azure AD Graph.Теперь наши усилия сфокусированы на разработке Microsoft Graph; дальнейшее продвижение API Azure AD Graph мы не планируем.Есть очень мало сценариев, в которых по-прежнему можно использовать API Azure AD Graph. Дополнительные сведения об этом см. в записи блога в центре разработчиков Office, где сравниваются решения Microsoft Graph и Azure AD Graph.
Обработка ошибок API Graph
Типы ошибок
Ошибки Graph API подразделяются на следующие категории.
- Ошибки клиента. Ошибки клиента представлены кодами состояния HTTP 400-й серии. Сюда входят объекты с неправильными значениями, объекты, у которых отсутствуют необходимые свойства или значения свойств, попытки доступа к несуществующему ресурсу, попытки обновления свойств, предназначенных только для чтения, и пропуск обязательного токена авторизации. Для устранения таких ошибок исправьте указанную проблему и повторите запрос.
- Ошибки сервера. Ошибки сервера, такие как временный сбой каталога, представлены кодами состояния HTTP 500-й серии. Большинство этих ошибок временные, и для их устранения можно просто повторить запрос.
- Ошибки сети и протокола. При отправке запроса или получении ответа могут возникать различные ошибки, связанные с сетью, такие как ошибки разрешения имен узлов, преждевременно закрытые соединения и ошибки согласования по протоколу SSL. Большинство этих ошибок не устраняется путем повторения запроса; указанную проблему необходимо исправить. Однако некоторые ошибки, например сбой разрешения имени узла или истечение времени ожидания, можно устранить, повторив запрос.
Структура сообщения об ошибке
Ошибки Graph API имеют форматированный текст, состоящий из кода состояния HTTP, сообщения и значений. Используйте свойства текста ошибки в логике обработки ошибок.
Примечание. Некоторые HTTP-ответы могут не включать текст ответа с кодом, сообщением или значениями, поскольку запрос направляется через службы прокси-сервера и шлюза. Убедитесь, что включили логику по умолчанию, которая может обрабатывать ошибки на основе только кода состояния HTTP.
Далее приводится пример ошибки HTTP 400 Request_BadRequest.
HTTP/1.1 400 Bad Request
Content-Type: application/json;odata=minimalmetadata;charset=utf-8
request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
Date: Tue, 02 Jul 2013 01:48:19 GMT
…
{
"odata.error" : {
"code" : "Request_BadRequest",
"message" : {
"lang" : "en",
"value" : "A value is required for property 'mailNickname' of resource 'Group'."
},
"values" : null
}
}
Текст сообщения всегда содержит код, сообщение и свойства.
Код: создайте ветку логики обработки ошибок на основе кода.
"code" : "Request_BadRequest"Сообщение: набор, состоящий из текста и значений, который представляет понятное сообщение об ошибке. Содержимое находится в поле значения. В следующем примере происходит сбой запроса, поскольку отсутствует значение свойства mailNickname.
"message" : { "lang" : "en", "value" : "A value is required for property 'mailNickname' of resource 'Group'." }Значения: набор пар "имя-значение", предоставляющий дополнительные сведения о природе сбоя. В следующем примере никаких значений нет.
"values" : null
Справочник по кодам ошибок
Коды ошибок HTTP
В следующей таблице перечислены коды ошибок API Graph, сообщения об ошибках и действия по их устранению.
В целом ошибки серии HTTP 500 связаны с повторными попытками, распределенными по увеличивающимся интервалам времени («повтор с интервалом отсрочки») и со случайным коэффициентом распределения. Ошибки серии 400 указывают на проблему, которую необходимо устранить перед выполнением повторной попытки.
| Код состояния HTTP | Код ошибки | Сообщение об ошибке | Подробные сведения |
|---|---|---|---|
| 400 | Directory_ExpiredPageToken | Срок действия токена указанной страницы истек и больше не может использоваться в запросе. | |
| 400 | Directory_ResultSizeLimitExceeded | Превышено ограничение размера результата | Запрос не может быть выполнен, поскольку он связан со слишком большим числом результатов.Эта ошибка происходит очень редко. |
| 400 | DomainVerificationCodeNotFound | Произошла ошибка проверки домена, так как в процессе проверки не удается найти запись TXT с соответствующим кодом проверки. | |
| 400 | ObjectConflict | Имя домена уже существует в непроверенном домене в этой организации. | |
| 400 | ObjectConflict | Имя домена уже существует в проверенном домене в этой организации. | |
| 400 | ObjectInUse | Не удается удалить домен, на который уже ссылается пользователь, группа или мультитенантное приложение. | |
| 400 | ObjectPendingDeletion | Не удается проверить существующий домен, который ожидает удаления. | |
| 400 | ObjectPendingTakeover | Не удается удалить домен в процессе перехвата клиента. | |
| 400 | Request_BadRequest | Ошибочный запрос.Исправьте запрос перед повтором. | Указывает на ошибку в запросе, например недопустимое значение свойства или аргумент запроса, который не поддерживается.Исправьте запрос перед повтором. |
| 400 | Request_DataContractVersionMissing | Не указан параметр версии контракта данных.В качестве параметра запроса добавляйте во все запросы значение api-version. | |
| 400 | Request_InvalidDataContractVersion | Указано недопустимое значение api-version.Значение должно точно соответствовать поддерживаемой версии. | |
| 400 | Request_InvalidRequestUrl | Недопустимый URL-адрес запроса.Запрос должен быть в формате /tenantdomainname/Entity или /$metadata.В качестве имени домена клиента можно использовать любое проверенное или непроверенное имя домена или идентификатор контекста. | |
| 400 | Request_UnsupportedQuery | Запрос GET не поддерживается.Исправьте параметры запроса и повторите попытку. | |
| 401 | Authentication_ExpiredToken | Срок действия токена доступа истек.Обновите его перед отправкой запроса. | Срок действия токена доступа истек.Обновите токен и отправьте его снова. |
| 401 | Authentication_MissingOrMalformed | Токен доступа отсутствует или имеет неправильный формат. | Значение access_token в заголовке авторизации отсутствует или имеет неправильный формат.Это значение является обязательным.Используйте это значение в токене проверки подлинности. |
| 401 | Authorization_IdentityDisabled | Участник вызывающего приложения отключен. | Участник, указанный в токене доступа, находится в каталоге, но он отключен.Повторно включите учетную запись в каталоге и повторите попытку. |
| 401 | Authorization_IdentityNotFound | Не удалось установить удостоверение вызывающего приложения. | Участник, указанный в токене доступа, не был найден в каталоге.Это может произойти из-за того, что токен устарел, участник был удален из каталога или синхронизация каталогов была задержана. |
| 403 | Authentication_Unauthorized | Запрос не авторизован. | Токен содержит недопустимые или неподдерживаемые утверждения.Получите токен запроса еще раз и повторите запрос. |
| 403 | Authorization_RequestDenied | Указанные учетные данные не имеют достаточно прав для этого запроса. | Запрос отклонен из-за недостатка прав.Например, у участника, не являющегося администратором, нет разрешения на удаление ресурса. |
| 403 | Directory_QuotaExceeded | Была превышена квота объекта каталога для {tenantName}.Попросите администратора увеличить квоту или удалить объекты для уменьшения используемой квоты. | Была превышена квота каталога.Возможно, что у клиента слишком много объектов или у объектов слишком много значений.Это также происходит, если для участника создано слишком много объектов.Увеличьте максимально допустимое число объектов для клиента или участника или уменьшите количество значений, включенных в запрос создания или обновления. |
| 404 | Directory_ObjectNotFound | Не удалось прочитать сведения об организации из каталога. | |
| 404 | Request_ResourceNotFound | Ресурс {resource} не существует, или отсутствует один из запрошенных объектов ссылочных свойств. | Ресурс, определенный URI, не существует.Измените значение и повторите запрос. |
| 409 | Request_MultipleObjectsWithSameKeyValue | Ожидалось, что результат будет содержать один ресурс, однако найдено несколько ресурсов.Чтобы разрешить конфликт, обновите объекты. | Эта ошибка может возникать при наличии двух и более объектов с одинаковым значением ключа (например, когда два пользователя используют одно имя участника-пользователя). |
| 429 | Слишком много запросов. | Эта ошибка возникает, когда запросы регулируются.Рекомендуемое время ожидания возвращается в значении Retry-After заголовка ответа.Повторите запрос после рекомендуемого времени ожидания (указано в секундах). | |
| 500 | Service_InternalServerError | Обнаружена внутренняя ошибка сервера. | Внутренняя ошибка сервера при обработке запроса. |
| 502 | [All] | “... Служба недоступна...» | Сервер, действующий как шлюз или прокси-сервер, обнаружил ошибку от другого сервера при обработке запроса.Подождите несколько минут, а затем повторите запрос. |
| 503 | Directory_ConcurrencyViolation | Ошибка, возникающая из-за одновременных запросов к клиенту.Подождите немного и повторите попытку. | |
| 503 | Ошибка при проверке DNS (она может вызываться различными причинами; например, DNS находится в неработоспособном состоянии). | ||
| Authentication_Unknown | Внутренняя ошибка сервера. | Этот код ошибки используется, если другие коды ошибки неприменимы. | |
| Authentication_UnsupportedTokenType | Предоставленный тип токена не обрабатывается.Поддерживаются только токены носителя. | Этот тип токена не поддерживается.Измените тип токена перед повтором запроса. | |
| Directory_BindingRedirection | Сведения о клиенте недоступны локально.Используйте следующие URL-адреса, чтобы получить сведения. | Если раздел клиента недоступен в центре обработки данных, клиенты должны подключаться к URL-адресу, возвращенному в ответе. | |
| Directory_BindingRedirectionInternalServerError | Сведения о клиенте недоступны локально.При попытке заполнить ближайшие конечные точки центра обработки данных на сервере возникла внутренняя ошибка. | При возникновении исключения перенаправления привязки заполняется список ближайших конечных точек центра обработки данных клиента для службы.Эта ошибка указывает на исключение, возникшее при заполнении списка.Попробуйте выполнить запрос еще раз. | |
| Directory_CompanyNotFound | Не удалось прочитать сведения об организации из каталога. | При загрузке сведений об организации из службы каталогов произошла ошибка. | |
| Directory_ReplicaUnavailable | Предпочитаемая реплика отсутствует.Повторите попытку без заголовка ключа сеанса реплики. | Пропустите заголовок ключа x-ms-replica-session, а затем повторите попытку. | |
| Headers_DataContractVersionMissing | Заголовок версии контракта данных недоступен.Включите x-ms-dirapi-data-contract-version в запрос. | Версия контракта клиента отсутствует в запросе. | |
| Headers_HeaderNotSupported | Заголовок {0} не поддерживается в текущей версии. | Запрос содержит неподдерживаемый заголовок HTTP.Измените заголовок и повторите запрос. | |
| Request_InvalidReplicaSessionKey | Указан недопустимый ключ сеанса реплики. | Исправьте ключ сеанса реплики и повторите запрос. | |
| Request_ThrottledPermanently | Ваш запрос регулируется постоянно.Для устранения этой проблемы обратитесь в службу поддержки. | Клиент повторно и постоянно превышает ограничение частоты запросов токена.Запросы от клиента отклоняются, пока служба не будет согласована.За помощью обратитесь в службу технической поддержки Майкрософт. |