Сведения о службе REST API управления сертификатами
В следующих разделах описаны сведения о REST API управления сертификатами (CM) Microsoft Identity Manager (MIM).
Архитектура
Вызовы REST API CM MIM обрабатываются контроллерами. В следующей таблице представлен полный список контроллеров и примеры контекста, в котором они используются.
| Контроллер | Образец маршрута |
|---|---|
| CertificateDataController | /api/v1.0/requests/{requestid}/certificatedata/ |
| CertificateRequestGenerationOptionsController | /api/v1.0/requests/{requestid} |
| CertificatesController | /api/v1.0/smartcards/{smartcardid}/certificates /api/v1.0/profiles/{profileid}/certificates |
| OperationsController | /api/v1.0/smartcards/{smartcardid}/operations /api/v1.0/profiles/{profileid}/operations |
| PoliciesController | /api/v1.0/profiletemplates/{profiletemplateid}/policies/{id} |
| ProfilesController | /api/v1.0/profiles/{id} |
| ProfileTemplatesController | /api/v1.0/profiletemplates/{id} /api/v1.0/profiletemplates /api/v1.0/profiletemplates/{profiletemplateid}/policies/{id} |
| RequestsController | /api/v1.0/requests/{id} /api/v1.0/requests |
| SmartcardsController | /api/v1.0/requests/{requestid}/smartcards/{id}/diversifiedkey /api/v1.0/requests/{requestid}/smartcards/{id}/serverproposedpin /api/v1.0/requests/{requestid}/smartcards/{id}/authenticationresponse /api/v1.0/requests/{requestid}/smartcards/{id} /api/v1.0/smartcards/{id} /api/v1.0/smartcards |
| SmartcardsConfigurationController | /api/v1.0/profiletemplates/{profiletemplateid}/configuration/smartcards |
Заголовки HTTP-запросов и ответов
HTTP-запросы, отправляемые в API, должны содержать следующие заголовки (этот список не является исчерпывающим):
| Header | Описание |
|---|---|
| Авторизация | Обязательный. Содержимое зависит от метода проверки подлинности. Метод настраивается и может основываться на встроенной проверке подлинности Windows (WIA) или службы федерации Active Directory (AD FS) (ADFS). |
| Content-Type | Требуется, если в запросе есть текст. Этот параметр должен содержать значение application/json. |
| Content-Length | Требуется, если в запросе есть текст. |
| Куки-файл | Файл cookie данного сеанса. Может потребоваться в зависимости от метода проверки подлинности. |
HTTP-ответы включают следующие заголовки (этот список не является исчерпывающим):
| Header | Описание |
|---|---|
| Content-Type | API всегда возвращает application/json. |
| Content-Length | Длина текста запроса, если он имеется, в байтах. |
Управление версиями API
Текущая версия интерфейса API REST CM — 1.0. Версия, указанная в сегменте непосредственно за сегментом /api в URI — /api/v1.0. Номер версии изменяется при внесении существенных изменений в интерфейс API.
Включение API
В раздел <ClmConfiguration> файла Web.config добавлен новый ключ:
<add key="Clm.WebApi.Enabled" value="false" />
Этот ключ определяет, доступен ли API REST CM клиентам. Если для ключа задано значение "false", сопоставление маршрута для API не выполняется при запуске приложения. Последующие запросы к конечным точкам API возвращают код ошибки HTTP 404. Ключ по умолчанию имеет значение "disabled".
Примечание
После изменения этого значения на true не забудьте запустить iisreset на сервере.
Включение трассировки и ведения журнала
API-интерфейс REST CM MIM передает данные трассировки для каждого отправленного ему HTTP-запроса. Вы можете изменить уровень детализации данных трассировки, указав следующее значение конфигурации:
<add name="Microsoft.Clm.Web.API" value="0" />
Обработка ошибок и устранение неполадок
При возникновении исключения во время обработки запроса API-интерфейс REST CM MIM возвращает код состояния HTTP веб-клиенту. Для типичных ошибок API возвращает соответствующий код состояния HTTP и код ошибки.
Необработанные исключения преобразуются в исключение HttpResponseException с кодом состояния HTTP код 500 ("Внутренняя ошибка") и записываются в журнал событий и файл трассировки MIM CM. Каждое необработанное исключение записывается в журнал событий с соответствующий идентификатором корреляции. Идентификатор корреляции также отправляется получателю API в сообщении об ошибке. Чтобы устранить ошибку, администратор может найти в журнале событий соответствующий идентификатор корреляции и сведения об ошибке.
Примечание
Трассировки стека, соответствующие ошибкам, которые создаются в результате использования REST API MIM CM, не отправляются обратно клиенту. Трассировки не отправляются клиенту из-за проблем с безопасностью.