Tanúsítványkezelő REST API-szolgáltatás részletes adataiCM REST API Service Details

Az alábbi szakaszok ismertetik a Microsoft Identity Manager (MIM) tanúsítványa (CM) felügyeleti REST API részleteit.The following sections discuss details of the Microsoft Identity Manager (MIM) Certificate Management (CM) REST API.

ArchitektúraArchitecture

MIM Tanúsítványkezelő REST API-hívások tartományvezérlők kezeli.MIM CM REST API calls are handled by controllers. A következő táblázat a tartományvezérlőket és a környezet, amelyben is használhatók minták teljes listáját jeleníti meg.The following table shows the full list of controllers and samples of the context in which they can be used.

TartományvezérlőController A minta útvonalSample route
CertificateDataControllerCertificateDataController /API/V1.0/Requests/{RequestId}/certificatedata //api/v1.0/requests/{requestid}/certificatedata /
CertificateRequestGenerationOptionsControllerCertificateRequestGenerationOptionsController /API/V1.0/Requests/{RequestId}/certificaterequestgenerationoptions/api/v1.0/requests/{requestid}/certificaterequestgenerationoptions
CertificatesControllerCertificatesController /API/V1.0/smartcards/{smartcardid}/Certificates/api/v1.0/smartcards/{smartcardid}/certificates
/API/V1.0/Profiles/{profileid}/Certificates/api/v1.0/profiles/{profileid}/certificates
OperationsControllerOperationsController /API/V1.0/smartcards/{smartcardid}/Operations/api/v1.0/smartcards/{smartcardid}/operations
/API/V1.0/Profiles/{profileid}/Operations/api/v1.0/profiles/{profileid}/operations
PoliciesControllerPoliciesController / api/v1.0/profiletemplates/{profiletemplateid}/policies/{id}/api/v1.0/profiletemplates/{profiletemplateid}/policies/{id}
ProfilesControllerProfilesController / api/v1.0/profiles/{id}/api/v1.0/profiles/{id}
/API/V1.0/Profiles/api/v1.0/Profiles
/ api/v1.0/requests/{requestid}/profiles/{id}/api/v1.0/requests/{requestid}/profiles/{id}
ProfileTemplatesControllerProfileTemplatesController / api/v1.0/profiletemplates/{id}/api/v1.0/profiletemplates/{id}
/API/V1.0/profiletemplates/api/v1.0/profiletemplates
/ api/v1.0/profiletemplates/{profiletemplateid}/policies/{id}/api/v1.0/profiletemplates/{profiletemplateid}/policies/{id}
RequestsControllerRequestsController / api/v1.0/requests/{id}/api/v1.0/requests/{id}
/API/V1.0/Requests/api/v1.0/requests
SmartcardsControllerSmartcardsController /API/V1.0/Requests/{RequestId}/smartcards/{ID}/diversifiedkey/api/v1.0/requests/{requestid}/smartcards/{id}/diversifiedkey
/API/V1.0/Requests/{RequestId}/smartcards/{ID}/serverproposedpin/api/v1.0/requests/{requestid}/smartcards/{id}/serverproposedpin
/API/V1.0/Requests/{RequestId}/smartcards/{ID}/authenticationresponse/api/v1.0/requests/{requestid}/smartcards/{id}/authenticationresponse
/ api/v1.0/requests/{requestid}/smartcards/{id}/api/v1.0/requests/{requestid}/smartcards/{id}
/ api/v1.0/smartcards/{id}/api/v1.0/smartcards/{id}
/API/V1.0/smartcards/api/v1.0/smartcards
SmartcardsConfigurationControllerSmartcardsConfigurationController /API/V1.0/profiletemplates/{profiletemplateid}/Configuration/smartcards/api/v1.0/profiletemplates/{profiletemplateid}/configuration/smartcards


HTTP-kérelmek és válaszfejlécekHTTP Request and Response Headers

Az API-nak küldött HTTP-kérelmekre a következő fejlécek (ebben a listában nincs teljes körű) kell tartalmaznia:HTTP Requests sent to the API should include the following headers (this list is not exhaustive):

FejlécHeader LeírásDescription
EngedélyezésAuthorization Kötelező.Required. A tartalom függvényében adható meg a hitelesítési módszer, amely konfigurálható, és WIA (integrált Windows-hitelesítés) vagy az AD FS alapulhat.The contents will depend on the authentication method, which is configurable and can be based on WIA (Windows Integrated Authentication) or ADFS.
TartalomtípusContent-Type Szükséges, ha a kérés van törzse.Required if the request has a body. "Application/json" kell lennie.Must be "application/json".
Content-LengthContent-Length Szükséges, ha a kérés van törzse.Required if the request has a body.
Cookie-kCookie A munkameneti cookie-ból.The session cookie. Hitelesítési módszertől függően szükség lehet.May be required depending on authentication method.


HTTP-válaszokat tartalmazza a következő fejlécek (ebben a listában nincs teljes körű):HTTP Responses will include the following headers (this list is not exhaustive):

FejlécHeader LeírásDescription
TartalomtípusContent-Type Az API-t mindig adja meg "az application/json".The API always returns "application/json".
Content-LengthContent-Length A kérelem törzsében, ha van ilyen, bájtban hosszát.The length of the request body, if present, in bytes.

API-VersioningAPI Versioning

A Tanúsítványkezelő REST API jelenlegi verziója 1.0.The current version of the CM REST API is 1.0. A verzió van megadva a közvetlenül a következő szegmens a /api szegmens URI azonosítójában: /api/v1.0.The version is specified in the segment directly following the /api segment in the URI: /api/v1.0. A jövőben változik a verziószám kell lényegesen módosul az API felületéhez.In the future, the version number will change should there be major changes to the API interface.

Az API-t engedélyezéseEnabling the API

A <ClmConfiguration> szakasz a Web.config fájl megtörtént-e új kulccsal:The <ClmConfiguration> section of the Web.config file has been extended with a new key:

<add key="Clm.WebApi.Enabled" value="false" />


Ez a kulcs határozza meg, hogy Tanúsítványkezelő REST API ügyfelek van kitéve.This key determines whether the CM REST API is exposed to clients. Ha a kulcs értéke "false", az API a útvonal leképezés nem történik alkalmazás következő indításakor.If the key is set to "false", the route mapping for the API is not performed on application startup. Ez azt jelenti, hogy bármely ezt követő kérelmek API-végpontokon visszaállítja-e egy HTTP 404 hibakód jelzi.This means that any subsequent requests to API endpoints will return an HTTP 404 error code. Alapértelmezés szerint a kulcs beállítva "letiltott".The key is set to “disabled” by default. Miután megváltoztatta ezt az értéket "true", ne felejtse el futtatása iisreset a kiszolgálón.After changing this value to "true", remember to run iisreset on the server.

Nyomkövetés és a naplózás engedélyezéseEnabling Tracing and Logging

A MIM Tanúsítványkezelő REST API-t az egyes neki küldött HTTP-kérelmek nyomkövetési adatok bocsát ki.The MIM CM REST API emits trace data for each HTTP request sent to it. A részletességi szint a nyomkövetési adatokat úgy, hogy a következő konfigurációs érték kibocsátott állíthatja be:You can set the verbosity level of the trace information emitted by setting the following configuration value:

<add name="Microsoft.Clm.Web.API" value="0" />


Hibakezelés és hibaelhárításError Handling and Troubleshooting

Amikor egy kérelem feldolgozása során kivétel lép fel, a MIM Tanúsítványkezelő REST API-t egy HTTP-állapotkód: a webes ügyféllel ad vissza.When exceptions occur while processing a request, the MIM CM REST API returns an HTTP status code to the web client. Gyakori hibák az API-t megfelelő HTTP-állapotkódot és egy hibakódot ad vissza.For common errors, the API returns an appropriate HTTP status code and an error code.

Nem kezelt kivételek alakítja át a rendszer egy HttpResponseException HTTP-állapot kód 500 ("belső Error"), és az Eseménynapló és a MIM CM nyomkövetési fájl is nyomon követni.Unhandled exceptions are converted to an HttpResponseException with HTTP Status Code 500 (“Internal Error”) and traced in both the event log and the MIM CM trace file. Nem kezelt kivételek írása az eseménynaplóba, a megfelelő korrelációs azonosítót.Each unhandled exception is written to the event log with a corresponding correlation ID. A fogyasztó az API a hibaüzenet a korrelációs azonosító is lett van küldve.The correlation ID is also sent to the consumer of the API in the error message. A hiba elhárításához egy rendszergazda kereshet a megfelelő korrelációs azonosítója és a hiba részleteit az eseménynaplóban találhatók.To troubleshoot the error, an administrator can search the event log for the corresponding correlation ID and error details.

Biztonsági okok miatt hibák miatt a MIM Tanúsítványkezelő REST API fel keletkeztek megfelelő híváslánc megjelenik nem kap az ügyfélnek.Due to security concerns, stack traces corresponding to errors generated as a result of consuming the MIM CM REST API are not sent back to the client.