Detalhes do serviço da API REST da Gestão de Certificados
As secções seguintes descrevem os detalhes da API REST de Gestão de Certificados (CM) Microsoft Identity Manager (MIM).
Arquitetura
As chamadas à API REST do CM do MIM são processadas por controladores. A tabela seguinte mostra a lista completa de controladores e exemplos do contexto em que podem ser utilizados.
| Controlador | Rota de exemplo |
|---|---|
| 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 |
Cabeçalhos de pedidos e respostas HTTP
Os pedidos HTTP enviados para a API devem incluir os seguintes cabeçalhos (esta lista não é exaustiva):
| Cabeçalho | Description |
|---|---|
| Autorização | Obrigatório. Os conteúdos dependem do método de autenticação. O método é configurável e pode basear-se na Autenticação Integrada do Windows (WIA)) ou Serviços de Federação do Active Directory (AD FS) (ADFS). |
| Content-Type | Necessário se o pedido tiver um corpo. Tem de ser application/json. |
| Comprimento do Conteúdo | Necessário se o pedido tiver um corpo. |
| Cookie | O cookie da sessão. Pode ser necessário consoante o 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 devolve application/jsonsempre . |
| Comprimento do Conteúdo | O comprimento do corpo do pedido, se estiver presente, em bytes. |
Controlo de versões da API
A versão atual da API REST do CM é 1.0. A versão é especificada no segmento diretamente a seguir ao /api segmento no URI: /api/v1.0. O número da versão é alterado quando são efetuadas modificações importantes na interface de API.
Ativar a API
A <ClmConfiguration> secção do ficheiro Web.config foi expandida com uma nova chave:
<add key="Clm.WebApi.Enabled" value="false" />
Esta chave determina se a API REST do CM está exposta aos clientes. Se a chave estiver definida como "false", o mapeamento de rotas para a API não é efetuado no arranque da aplicação. Os pedidos subsequentes aos pontos finais da API devolvem um código de erro HTTP 404. A chave está definida como "desativada" por predefinição.
Nota
Depois de alterar este valor para "verdadeiro", lembre-se de executar iisreset no servidor.
Ativar o rastreio e o registo
A API REST do CM do MIM emite dados de rastreio para cada pedido HTTP enviado para o mesmo. Pode definir o nível de verbosidade das informações de rastreio emitidas ao definir o seguinte valor de configuração:
<add name="Microsoft.Clm.Web.API" value="0" />
Resolução de problemas e processamento de erros
Quando ocorrem exceções durante o processamento de um pedido, a API REST do CM do MIM 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 processadas são convertidas num HttpResponseException com o Código de Estado HTTP 500 ("Erro Interno") e rastreadas no registo de eventos e no ficheiro de rastreio CM do MIM. Cada exceção não processada é escrita no registo de eventos 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 procurar no registo de eventos o ID de correlação correspondente e os detalhes do erro.
Nota
Os rastreios de pilha que correspondem a erros, que são gerados como resultado do consumo da API REST do CM do MIM, não são enviados de volta para o cliente. Os rastreios não são enviados de volta para o cliente devido a questões de segurança.