Information om CM REST API-tjänstenCM REST API Service Details

I följande avsnitt beskrivs information om Microsoft Identity Manager (MIM) certifikat Management CM REST API.The following sections discuss details of the Microsoft Identity Manager (MIM) Certificate Management (CM) REST API.

ArkitekturArchitecture

MIM CM REST API-anrop som hanteras av domänkontrollanter.MIM CM REST API calls are handled by controllers. I följande tabell visas en fullständig lista över kontrollanter och exempel på kontexten där de kan användas.The following table shows the full list of controllers and samples of the context in which they can be used.

DomänkontrollantController Exempel vägSample 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-begäran och svarshuvudenHTTP Request and Response Headers

HTTP-begäranden skickas till API: N bör innehålla följande huvuden (den här listan inte är fullständig):HTTP Requests sent to the API should include the following headers (this list is not exhaustive):

SidhuvudHeader BeskrivningDescription
AuktoriseringAuthorization Obligatoriskt.Required. Innehållet beror på den autentiseringsmetod som kan konfigureras och kan baseras på WIA (Windows-integrerad autentisering) eller AD FS.The contents will depend on the authentication method, which is configurable and can be based on WIA (Windows Integrated Authentication) or ADFS.
InnehållstypContent-Type Krävs om begäran har en brödtext.Required if the request has a body. Måste vara ”application/json”.Must be "application/json".
Content-LengthContent-Length Krävs om begäran har en brödtext.Required if the request has a body.
CookieCookie Sessions-cookie.The session cookie. Kan krävas beroende på vilken autentiseringsmetod du valde.May be required depending on authentication method.


HTTP-svar innehåller följande huvuden (den här listan inte är fullständig):HTTP Responses will include the following headers (this list is not exhaustive):

SidhuvudHeader BeskrivningDescription
InnehållstypContent-Type API: et och returnerar ”application/json”.The API always returns "application/json".
Content-LengthContent-Length Längden på begärantext om den finns, i byte.The length of the request body, if present, in bytes.

API-versionAPI Versioning

Den aktuella versionen av CM REST API är 1,0.The current version of the CM REST API is 1.0. Versionen som har angetts i segmentet direkt efter den /api segment i URI: /api/v1.0.The version is specified in the segment directly following the /api segment in the URI: /api/v1.0. I framtiden, versionsnumret ändras bör det finnas betydande ändringar i API-gränssnitt.In the future, the version number will change should there be major changes to the API interface.

Aktivera API: etEnabling the API

Den <ClmConfiguration> avsnitt i Web.config-filen har utökats med en ny nyckel:The <ClmConfiguration> section of the Web.config file has been extended with a new key:

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


Den här nyckeln avgör om CM REST API exponeras för klienter.This key determines whether the CM REST API is exposed to clients. Om nyckeln är inställd på ”false”, utförs inte vägen mappningen för API: et på Start av program.If the key is set to "false", the route mapping for the API is not performed on application startup. Det innebär att alla efterföljande begäranden till API-slutpunkter returnerar ett HTTP-fel 404.This means that any subsequent requests to API endpoints will return an HTTP 404 error code. Nyckeln är standardinställningen på ”inaktiverad”.The key is set to “disabled” by default. När du har ändrat värdet ”true” Kom ihåg att köra iisreset på servern.After changing this value to "true", remember to run iisreset on the server.

Aktivera spårning och loggningEnabling Tracing and Logging

MIM CM REST API avger spårningsdata för varje HTTP-begäran skickas till den.The MIM CM REST API emits trace data for each HTTP request sent to it. Du kan ange nivån av spårningsinformation orsakat genom att ange Konfigurationsvärdet för följande: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" />


Felhantering och felsökningError Handling and Troubleshooting

När undantag inträffar när en begäran bearbetades returnerar en HTTP-statuskod och webbklienten MIM CM REST API.When exceptions occur while processing a request, the MIM CM REST API returns an HTTP status code to the web client. Vanliga fel returnerar API: et lämplig HTTP-statuskoden och en felkod.For common errors, the API returns an appropriate HTTP status code and an error code.

Ohanterade undantag som konverteras till en HttpResponseException med HTTP-Status 500 (”internt fel”) och spåras i både i händelseloggen och spårningsfilen MIM CM.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. Varje undantag skrivs till händelseloggen med en motsvarande Korrelations-IDEach unhandled exception is written to the event log with a corresponding correlation ID. Korrelations-ID skickas även till konsumenten API i felmeddelandet.The correlation ID is also sent to the consumer of the API in the error message. Åtgärda felet, kan en administratör söka motsvarande Korrelations-ID och fel information i händelseloggen.To troubleshoot the error, an administrator can search the event log for the corresponding correlation ID and error details.

På grund av säkerhetsfrågor skickas stackspår som motsvarar de fel som har genererats av förbrukar MIM CM REST API inte tillbaka till klienten.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.