憑證管理 REST API 服務詳細資料
下列各節說明MICROSOFT IDENTITY MANAGER (MIM) 憑證管理 (CM) REST API 的詳細資料。
架構
MIM CM REST API 呼叫是由控制器處理。 下表顯示完整的控制器清單及其可派上用場的情況範例。
| 控制器 | 範例路由 |
|---|---|
| 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 要求和回應標頭
傳送至 API 的 HTTP 要求應包含下列標頭， (此清單並非詳盡) ：
| 標頭 | 描述 |
|---|---|
| 授權 | 必要。 內容取決於驗證方法。 方法可設定，而且可以根據 Windows 整合式驗證 (WIA) ) 或Active Directory 同盟服務 (ADFS) 。 |
| Content-Type | 如果要求有內文，則為必要。 必須是 application/json。 |
| Content-Length | 如果要求有內文，則為必要。 |
| Cookie | 工作階段 Cookie。 根據驗證方法而定，可能為必要。 |
HTTP 回應包含下列標頭， (此清單並非詳盡) ：
| 標頭 | 描述 |
|---|---|
| Content-Type | API 一律會傳 application/json 回 。 |
| Content-Length | 要求本文 (如果有的話) 的長度 (以位元組為單位)。 |
API 版本控制
CM REST API 的目前版本為 1.0。 版本是在 URI 中緊接於 /api 區段後的區段中指定： /api/v1.0。 對 API 介面進行重大修改時，版本號碼會變更。
啟用 API
Web.config 檔案的 <ClmConfiguration> 區段已擴充加上新的機碼：
<add key="Clm.WebApi.Enabled" value="false" />
此機碼決定是否將 CM REST API 公開給用戶端。 如果此機碼設為 "false"，則不會在應用程式啟動時執行 API 的路由對應。 API 端點的後續要求會傳回 HTTP 404 錯誤碼。 此機碼預設為 "disabled"。
注意
將此值變更為 「true」 之後，請記得在伺服器上執行 iisreset 。
啟用追蹤和記錄
MIM CM REST API 會對每個送來的 HTTP 要求，發出追蹤資料。 您可以設定下列設定值，以設定發出詳細等級的追蹤資訊：
<add name="Microsoft.Clm.Web.API" value="0" />
錯誤處理和疑難排解
當處理要求發生例外狀況時，MIM CM REST API 會傳回 HTTP 狀態碼給 Web 用戶端。 對於常見的錯誤，API 會傳回適當的 HTTP 狀態碼和錯誤碼。
未處理的例外狀況會轉換成 HttpResponseException ，HTTP 狀態碼為 500 (「內部錯誤」)，而且記錄在事件記錄檔和 MIM CM 追蹤檔案中追蹤。 每個未處理的例外狀況會連同對應的相互關聯識別碼，一起寫入事件記錄檔中。 相互關聯識別碼也會透過錯誤訊息傳送給 API 取用者。 若要對錯誤進行疑難排解，系統管理員可以在事件記錄檔中，搜尋對應的相互關聯識別碼和錯誤詳細資料。
注意
對應至因使用 MIM CM REST API 而產生之錯誤的堆疊追蹤不會傳回給用戶端。 由於安全性考慮，追蹤不會傳回給用戶端。