Szczegóły usługi INTERFEJSu API REST zarządzania certyfikatami

Artykuł
09/14/2023

W poniższych sekcjach opisano szczegóły interfejsu API REST zarządzania certyfikatami Microsoft Identity Manager (MIM).

Architektura

Wywołania interfejsu API REST programu MIM są obsługiwane przez kontrolery. W poniższej tabeli przedstawiono pełną listę kontrolerów i przykładów kontekstu, w którym można ich używać.

Kontroler	Przykładowa trasa
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

Nagłówki żądań HTTP i odpowiedzi

Żądania HTTP wysyłane do interfejsu API powinny zawierać następujące nagłówki (ta lista nie jest wyczerpująca):

Nagłówek	Opis
Autoryzacja	Wymagane. Zawartość zależy od metody uwierzytelniania. Metoda jest konfigurowalna i może być oparta na zintegrowanym uwierzytelnianiu systemu Windows (WIA) lub Active Directory Federation Services (ADFS).
Content-Type	Wymagane, jeśli żądanie ma treść. Musi mieć wartość `application/json`.
Długość zawartości	Wymagane, jeśli żądanie ma treść.
Cookie	Plik cookie sesji. Może być wymagane w zależności od metody uwierzytelniania.

Odpowiedzi HTTP obejmują następujące nagłówki (ta lista nie jest wyczerpująca):

Nagłówek	Opis
Content-Type	Interfejs API zawsze zwraca wartość `application/json`.
Długość zawartości	Długość treści żądania, jeśli jest obecna, w bajtach.

Przechowywanie wersji interfejsu API

Bieżąca wersja interfejsu API REST cm to 1.0. Wersja jest określona w segmencie bezpośrednio po /api segmencie w identyfikatorze URI: /api/v1.0. Numer wersji zmienia się po wprowadzeniu istotnych modyfikacji interfejsu API.

Włączanie interfejsu API

Sekcja <ClmConfiguration> pliku Web.config została rozszerzona o nowy klucz:

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

Ten klucz określa, czy interfejs API REST cm jest udostępniany klientom. Jeśli klucz ma wartość "false", mapowanie tras dla interfejsu API nie jest wykonywane podczas uruchamiania aplikacji. Kolejne żądania do punktów końcowych interfejsu API zwracają kod błędu HTTP 404. Klucz jest domyślnie ustawiony na wartość "disabled".

Uwaga

Po zmianie tej wartości na "true" pamiętaj, aby uruchomić usługę iisreset na serwerze.

Włączanie śledzenia i rejestrowania

Interfejs API REST programu MIM cm emituje dane śledzenia dla każdego wysłanego do niego żądania HTTP. Możesz ustawić poziom szczegółowości informacji śledzenia emitowanych przez ustawienie następującej wartości konfiguracji:

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

Obsługa błędów i rozwiązywanie problemów

Gdy wystąpią wyjątki podczas przetwarzania żądania, interfejs API REST programu MIM CM zwraca kod stanu HTTP do klienta internetowego. W przypadku typowych błędów interfejs API zwraca odpowiedni kod stanu HTTP i kod błędu.

Nieobsługiwane wyjątki są konwertowane na HttpResponseException kod stanu HTTP 500 ("Błąd wewnętrzny") i śledzone zarówno w dzienniku zdarzeń, jak i w pliku śledzenia programu MIM CM. Każdy nieobsługiwany wyjątek jest zapisywany w dzienniku zdarzeń z odpowiednim identyfikatorem korelacji. Identyfikator korelacji jest również wysyłany do użytkownika interfejsu API w komunikacie o błędzie. Aby rozwiązać problem z błędem, administrator może wyszukać odpowiedni identyfikator korelacji i szczegóły błędu.