Podrobnosti o službě REST API pro správu certifikátů

Následující části popisují podrobnosti o rozhraní REST API Microsoft Identity Manager (MIM) Certificate Management (CM).

Architektura

Volání rozhraní REST API MIM CM zpracovávají kontrolery. Následující tabulka uvádí úplný seznam kontrolerů a ukázky kontextu, ve kterém je lze použít.

Controller	Ukázková trasa
CertificateDataController	/api/v1.0/requests/{requestid}/certificatedata/
CertificateRequestGenerationOptionsController	/api/v1.0/requests/{requestid}
CertifikátyController	/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
ZásadyController	/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}/diverzifikacekey /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

Hlavičky požadavků HTTP a odpovědí

Požadavky HTTP odeslané do rozhraní API by měly obsahovat následující hlavičky (tento seznam není vyčerpávající):

Hlavička	Description
Autorizace	Povinná hodnota. Obsah závisí na metodě ověřování. Metoda je konfigurovatelná a může být založena na integrovaném ověřování systému Windows (WIA)) nebo Active Directory Federation Services (AD FS) (AD FS).
Typ obsahu	Vyžaduje se, pokud má požadavek text. Musí být application/json.
Délka obsahu	Vyžaduje se, pokud má požadavek text.
Soubor cookie	Soubor cookie relace. V závislosti na metodě ověřování se může vyžadovat.

Odpovědi HTTP obsahují následující hlavičky (tento seznam není vyčerpávající):

Hlavička	Description
Typ obsahu	Rozhraní API vždy vrátí application/json.
Délka obsahu	Délka textu požadavku v bajtech, pokud je k dispozici.

Správa verzí rozhraní API

Aktuální verze rozhraní REST API cm je 1.0. Verze se zadává v segmentu přímo za segmentem /api v identifikátoru URI: /api/v1.0. Číslo verze se změní, když dojde k významným úpravám rozhraní API.

Povolení rozhraní API

Oddíl <ClmConfiguration> souboru Web.config byl rozšířen o nový klíč:

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

Tento klíč určuje, jestli je rozhraní REST API CM vystaveno klientům. Pokud je klíč nastavený na false, mapování tras pro rozhraní API se při spuštění aplikace neprovádí. Následné požadavky na koncové body rozhraní API vrátí kód chyby HTTP 404. Klíč je ve výchozím nastavení nastavený na zakázáno.

Poznámka

Po změně této hodnoty na true nezapomeňte na serveru spustit iisreset .

Povolení trasování a protokolování

Rozhraní REST API MIM CM generuje data trasování pro každý odeslaný požadavek HTTP. Úroveň podrobností vygenerovaných trasovacích informací můžete nastavit nastavením následující hodnoty konfigurace:

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

Zpracování chyb a řešení potíží

Pokud při zpracování požadavku dojde k výjimkám, vrátí rozhraní REST API MIM CM do webového klienta stavový kód HTTP. V případě běžných chyb vrátí rozhraní API odpovídající stavový kód HTTP a kód chyby.

Neošetřené výjimky se převedou na stavový HttpResponseException kód HTTP 500 ("vnitřní chyba") a trasují se v protokolu událostí i v trasovacím souboru MIM CM. Každá neošetřená výjimka se zapíše do protokolu událostí s odpovídajícím ID korelace. ID korelace se také odešle příjemci rozhraní API v chybové zprávě. Při řešení chyby může správce vyhledat v protokolu událostí odpovídající ID korelace a podrobnosti o chybě.

Poznámka

Trasování zásobníku, která odpovídají chybám vygenerovaným v důsledku využití rozhraní REST API MIM CM, se do klienta neodesílají zpět. Trasování se klientovi neodesílají zpět kvůli obavám o zabezpečení.