Detalhes do serviço API de Gestão de Certificados REST

As seguintes secções descrevem detalhes da Microsoft Identity Manager (MIM) Gestão de Certificados (CM) REST API.

Arquitetura

MIM as chamadas CM REST API são tratadas por controladores. A tabela a seguir mostra a lista completa dos controladores e amostras do contexto em que podem ser utilizados.

Controlador Rota da amostra
CertificadoDataController /api/v1.0/requests/{requestid}/certificatedata/
CertificadoRequestGenerationOptionsController /api/v1.0/requests/{requestid}
Certificadocontrolador /api/v1.0/smartcards/{smartcardid}/certificados
/api/v1.0/profiles/{profileid}/certificados
Controlador de Operações /api/v1.0/smartcards/{smartcardid}/operações
/api/v1.0/profiles/{profileid}/operações
PolíticasControlador /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}
RequererController /api/v1.0/requests/{id}
/api/v1.0/pedidos
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 pedido e cabeçalhos de resposta

Os pedidos HTTP enviados à API devem incluir os seguintes cabeçalhos (esta lista não é exaustiva):

Cabeçalho Description
Autorização Obrigatório. O conteúdo depende do método de autenticação. O método é configurável e pode basear-se em Windows Serviços integrados de Autenticação (WIA) ou na Federação de Diretórios Ativos (ADFS).
Content-Type Obrigatório se o pedido tiver um corpo. Deve application/json ser.
Comprimento do conteúdo Obrigatório se o pedido tiver um corpo.
Cookie O biscoito da sessão. Pode ser necessário dependendo do método de autenticação.

As respostas HTTP incluem os seguintes cabeçalhos (esta lista não é exaustiva):

Cabeçalho Description
Content-Type A API regressa application/json sempre.
Comprimento do conteúdo O comprimento do corpo pedido, se presente, em bytes.

Versão API

A versão atual da CM REST API é 1.0. A versão é especificada no segmento que segue diretamente o /api segmento no URI: /api/v1.0 . O número de versão muda quando são feitas grandes modificações na interface API.

Ativar a API

A <ClmConfiguration> secção do ficheiro Web.config foi alargada com uma nova chave:

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

Esta chave determina se a CM REST API está exposta aos clientes. Se a chave estiver definida como "falsa", o mapeamento de rota para a API não é realizado no arranque de aplicações. Os pedidos subsequentes aos pontos finais da API devolvem um código de erro HTTP 404. A chave está definida para "desativado" por defeito.

Nota

Depois de mudar este valor para "verdadeiro", lembre-se de executar iisreset no servidor.

Ativar o rastreio e a exploração madeireira

A MIM CM REST A API emite vestígios de dados para cada pedido HTTP que lhe é enviado. Pode definir o nível de verbosidade das informações de traços emitidas definindo o seguinte valor de configuração:

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

Manipulação de erros e resolução de problemas

Quando ocorrem exceções durante o processamento de um pedido, a API MIM CM REST devolve um código de estado HTTP ao cliente web. Para erros comuns, a API devolve um código de estado HTTP adequado e um código de erro.

As exceções não tratadas são convertidas para um HttpResponseException código de estado HTTP 500 ("Erro Interno") e traçadas tanto no registo de eventos como no ficheiro de traços CM MIM. Cada exceção não manipulada é escrita no registo do evento com um ID de correlação correspondente. O ID de correlação também é enviado ao consumidor da API na mensagem de erro. Para resolver o erro, um administrador pode pesquisar o registo do evento para obter o ID de correlação correspondente e detalhes de erro.

Nota

Os vestígios de stack que correspondem a erros, que são gerados como resultado do consumo da MIM CM REST API, não são devolvidos ao cliente. Os vestígios não são enviados de volta para o cliente devido a questões de segurança.