Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
APLICA-SE A: Todas as camadas de gerenciamento de API
Quando cria uma instância de serviço de Gestão de API do Azure na nuvem do Azure, o Azure atribui-lhe um azure-api.net subdomínio (por exemplo, apim-service-name.azure-api.net). Você também pode expor seus pontos de extremidade de Gerenciamento de API usando seu próprio nome de domínio personalizado, como contoso.com. Este artigo mostra como mapear um nome DNS personalizado existente para endpoints expostos por uma instância de API Management.
Importante
O Gerenciamento de API só aceita solicitações com valores de cabeçalho de host correspondentes:
- O nome de domínio padrão do gateway
- Qualquer um dos nomes de domínio personalizados configurados do Gateway
Nota
Atualmente, nomes de domínio personalizados não são suportados em um gateway de espaço de trabalho.
Importante
As alterações na infraestrutura do serviço de Gerenciamento de API (como configuração de domínios personalizados, adição de certificados de CA, dimensionamento, configuração de rede virtual, alterações de zona de disponibilidade e adições de região) podem levar 15 minutos ou mais para serem concluídas, dependendo da camada de serviço e do tamanho da implantação. Espere tempos mais longos para uma instância com um número maior de unidades de escala ou configuração de várias regiões. As alterações contínuas no Gerenciamento de API são executadas cuidadosamente para preservar a capacidade e a disponibilidade.
Enquanto o serviço está sendo atualizado, outras alterações na infraestrutura do serviço não podem ser feitas. No entanto, você pode definir APIs, produtos, políticas e configurações de usuário. O serviço não enfrentará tempo de inatividade do gateway e o Gerenciamento de API continuará a atender solicitações de API sem interrupção (exceto na camada de desenvolvedor).
Pré-requisitos
Uma instância de gerenciamento de API. Para obter mais informações, consulte Criar uma instância de Gerenciamento de API do Azure.
Um nome de domínio personalizado que pertence a si ou à sua organização. Este artigo não fornece instruções sobre como obter um nome de domínio personalizado.
Opcionalmente, um certificado válido com uma chave pública e privada (. PFX). O assunto ou o nome alternativo do assunto (SAN) deve corresponder ao nome de domínio (isso permite que a instância de Gerenciamento de API exponha URLs com segurança por TLS).
Consulte Opções de certificado de domínio.
Registros DNS hospedados em um servidor DNS para mapear o nome de domínio personalizado para o nome de domínio padrão da sua instância de Gerenciamento de API. Este tópico não fornece instruções sobre como hospedar os registros DNS.
Para obter mais informações sobre os registros necessários, consulte Configuração de DNS, mais adiante neste artigo.
Pontos de extremidade para domínios personalizados
Há vários pontos de extremidade de Gerenciamento de API aos quais você pode atribuir um nome de domínio personalizado. Atualmente, os seguintes endpoints estão disponíveis:
| Ponto final | Predefinido |
|---|---|
| Porta de entrada | O padrão é: <apim-service-name>.azure-api.net. O Gateway é o único ponto de extremidade disponível para configuração na camada de Consumo.A configuração padrão do ponto de extremidade do Gateway permanece disponível depois que um domínio de Gateway personalizado é adicionado. |
| Portal do desenvolvedor (todos os níveis, exceto Consumo) | O padrão é: <apim-service-name>.developer.azure-api.net |
| Gerenciamento (somente níveis clássicos) | O padrão é: <apim-service-name>.management.azure-api.net |
| API de configuração de gateway auto-hospedado (v2) | O padrão é: <apim-service-name>.configuration.azure-api.net |
| SCM (apenas níveis clássicos) | O padrão é: <apim-service-name>.scm.azure-api.net |
Considerações
- Pode atualizar qualquer um dos endpoints suportados no seu escalão de serviço. Normalmente, os clientes atualizam o Gateway (este URL é utilizado para chamar as APIs expostas através da Gestão de API) e o Portal do programador (o URL do portal do programador).
- O ponto de extremidade padrão do Gateway permanece disponível após a configuração de um nome de domínio personalizado do Gateway e não pode ser excluído. Para outros pontos de extremidade de Gerenciamento de API (como o Portal do desenvolvedor) que você configura com um nome de domínio personalizado, o ponto de extremidade padrão não está mais disponível.
- Apenas os proprietários da instância da Gestão de API podem utilizar os endpoints Gestão e SCM internamente. São atribuídos com menos frequência um nome de domínio personalizado a estes endpoints.
- Os escalões Premium e Programador suportam a definição de vários nomes de anfitrião para o ponto final do Gateway.
- Nomes de domínio curinga, como
*.contoso.com, são suportados em todas as camadas, exceto na camada Consumo. Um certificado de subdomínio específico (por exemplo, api.contoso.com) teria precedência sobre um certificado curinga (*.contoso.com) para solicitações de api.contoso.com. - Ao configurar um domínio personalizado para o portal do desenvolvedor, você pode habilitar o CORS para o novo nome de domínio. Isso é necessário para que os visitantes do portal do desenvolvedor usem o console interativo nas páginas de referência da API.
Opções de certificado de domínio
A Gestão de API suporta certificados TLS personalizados ou certificados importados do Azure Key Vault. Também pode ativar um certificado gerido gratuito.
Aviso
Se você precisar de fixação de certificado, use um nome de domínio personalizado e um certificado personalizado ou do Cofre da Chave, não o certificado padrão ou o certificado gerenciado gratuito. Não recomendamos que assuma uma dependência rígida de um certificado que não é gerido por si.
Se você já tiver um certificado privado de um provedor de terceiros, poderá carregá-lo em sua instância de Gerenciamento de API. Deve satisfazer os seguintes requisitos: (Se você habilitar o certificado gratuito gerenciado pelo Gerenciamento de API, ele já atende a esses requisitos.)
- Exportado como ficheiro PFX, encriptado com DES triplo e, opcionalmente, protegido por palavra-passe.
- Contém chave privada com pelo menos 2.048 bits de comprimento
- Conter todos os certificados intermédios e o certificado de raiz na cadeia de certificados.
Definir um nome de domínio personalizado - portal
Escolha as etapas de acordo com o certificado de domínio que deseja usar.
- Navegue até sua instância de Gerenciamento de API no portal do Azure.
- Na navegação à esquerda, selecione Domínios personalizados.
- Selecione +Adicionar ou selecione um ponto de extremidade existente que você deseja atualizar.
- Na janela à direita, selecione o Tipo de ponto de extremidade para o domínio personalizado.
- No campo Nome do host , especifique o nome que deseja usar. Por exemplo,
api.contoso.com. - Em Certificado, selecione Personalizado
- Selecione Arquivo de certificado para selecionar e carregar um certificado.
- Carregue um ficheiro .PFX válido e forneça a palavra-passe, caso o certificado esteja protegido por palavra-passe.
- Ao configurar um ponto de extremidade de gateway, selecione ou desmarque outras opções conforme necessário, incluindo Negociar certificado do cliente ou Associação SSL padrão.
- Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
- Selecione Guardar.
Configuração do DNS
- Configure um registro CNAME para seu domínio personalizado.
- Ao usar o certificado gerenciado gratuito do Gerenciamento de API, configure também um registro TXT para estabelecer sua propriedade do domínio.
Nota
O certificado gratuito é emitido pela DigiCert. Para alguns domínios, você deve permitir explicitamente o DigiCert como um emissor de certificado criando um registro de domínio CAA com o valor: 0 issue digicert.com.
Registo CNAME
Configure um registro CNAME que aponte do seu nome de domínio personalizado (por exemplo, api.contoso.com) para o nome de host do serviço de Gerenciamento de API (por exemplo, <apim-service-name>.azure-api.net). Um registro CNAME é mais estável do que um registro A caso o endereço IP mude. Para obter mais informações, consulte Endereços IP do Gerenciamento de API do Azure e as Perguntas frequentes sobre Gerenciamento de API.
Nota
Alguns registradores de domínio só permitem mapear subdomínios ao usar um registro CNAME, como www.contoso.com, e não nomes de raiz, como contoso.com. Para obter mais informações sobre registros CNAME, consulte a documentação fornecida pelo seu registrador ou IETF Domain Names - Implementation and Specification.
Atenção
Quando você usa o certificado gerenciado gratuito e configura um registro CNAME com seu provedor de DNS, certifique-se de que ele seja resolvido para o nome de host do serviço de Gerenciamento de API padrão (<apim-service-name>.azure-api.net). Atualmente, o Gerenciamento de API não renova automaticamente o certificado se o registro CNAME não resolver para o nome de host padrão do Gerenciamento de API. Por exemplo, se você estiver usando o certificado gerenciado gratuito e usar a Cloudflare como seu provedor de DNS, verifique se o proxy DNS não está habilitado no registro CNAME.
Registo TXT
Ao habilitar o certificado gerenciado gratuito para Gerenciamento de API, configure também um registro TXT em sua zona DNS para estabelecer sua propriedade do nome de domínio.
- O nome do registro é seu nome de domínio personalizado prefixado por
apimuid. Exemplo:apimuid.api.contoso.com. - O valor é um identificador de propriedade de domínio fornecido pela sua instância de Gerenciamento de API.
Quando você usa o portal para configurar o certificado gerenciado gratuito para seu domínio personalizado, o nome e o valor do registro TXT necessário são exibidos automaticamente.
Você também pode obter um identificador de propriedade de domínio chamando a API REST Get Domain Ownership Identifier .
Como o servidor proxy do Gerenciamento de API responde com certificados SSL no handshake TLS
Ao configurar um domínio personalizado para o ponto de extremidade do Gateway, você pode definir propriedades adicionais que determinam como o Gerenciamento de API responde com um certificado de servidor, dependendo da solicitação do cliente.
Clientes que chamam com o cabeçalho SNI (Indicação de Nome do Servidor)
Se você tiver um ou vários domínios personalizados configurados para o ponto de extremidade do Gateway, o Gerenciamento de API poderá responder a solicitações HTTPS de:
- Domínio personalizado (por exemplo,
contoso.com) - Domínio padrão (por exemplo,
apim-service-name.azure-api.net).
Com base nas informações no cabeçalho SNI, o Gerenciamento de API responde com o certificado de servidor apropriado.
Clientes que ligam sem cabeçalho SNI
Se você estiver usando um cliente que não envia o cabeçalho SNI, o Gerenciamento de API criará respostas com base na seguinte lógica:
Se o serviço tiver apenas um domínio personalizado configurado para o Gateway, o certificado padrão será o certificado emitido para o domínio personalizado do Gateway.
Se o serviço tiver configurado vários domínios personalizados para Gateway (suportados nas camadas Developer e Premium), você poderá designar o certificado padrão definindo a propriedade defaultSslBinding como true (
"defaultSslBinding":"true"). No portal, selecione a caixa de seleção SSL padrão.Se você não definir a propriedade, o certificado padrão será o certificado emitido para o domínio Gateway padrão hospedado em
*.azure-api.net.
Suporte para requisição PUT/POST com grande volume de dados
O servidor proxy de Gerenciamento de API aceita pedidos com cargas úteis grandes (>40 KB) ao usar certificados de cliente em HTTPS. Para impedir que a requisição do servidor fique congelada, podeis definir a propriedade negotiateClientCertificate como true ("negotiateClientCertificate": "true") no nome do host do gateway. Marque a caixa de seleção Negociar certificado de cliente no portal.
Se a propriedade estiver definida como true, o certificado do cliente será solicitado no momento da conexão SSL/TLS, antes de qualquer troca de solicitação HTTP. Como a configuração se aplica ao nível do nome de host do gateway, todas as solicitações de conexão exigem o certificado do cliente. Você pode contornar essa limitação e configurar até 20 domínios personalizados para o Gateway (suportados apenas na camada Premium ).
Limitação para nome de domínio personalizado na camada Standard v2
Atualmente, na camada Standard v2, o Gerenciamento de API requer um nome DNS resolúvel publicamente para permitir o tráfego para o ponto de extremidade do Gateway. Se você configurar um nome de domínio personalizado para o ponto de extremidade do Gateway, esse nome deverá ser resolúvel publicamente, não restrito a uma zona DNS privada.
Como solução alternativa em cenários em que você limita o acesso público ao gateway e configura um nome de domínio privado, você pode configurar o Application Gateway para receber tráfego no nome de domínio privado e roteá-lo para o ponto de extremidade do Gateway da instância de Gerenciamento de API. Para obter um exemplo de arquitetura, consulte este repositório GitHub.
Solução de problemas: Falha na rotação do certificado de nome de host do Cofre de Chaves do Azure
Devido a uma alteração de configuração ou problema de conectividade, sua instância de Gerenciamento de API pode não conseguir buscar um certificado de nome de host no Cofre de Chaves do Azure depois que um certificado for atualizado ou girado lá. Quando isso acontece, sua instância de Gerenciamento de API continua a usar um certificado armazenado em cache até receber um certificado atualizado. Se o certificado armazenado em cache expirar, o tráfego de tempo de execução para o gateway será bloqueado. Qualquer serviço upstream, como o Application Gateway, que use a configuração de certificado de nome de host também pode bloquear o tráfego de tempo de execução para o gateway quando um certificado armazenado em cache expirado é usado.
Para atenuar esse problema, confirme se o cofre de chaves existe e se o certificado está armazenado no cofre de chaves. Se sua instância de Gerenciamento de API for implantada em uma rede virtual, confirme a conectividade de saída com a marca de serviço AzureKeyVault. Verifique se a identidade gerenciada usada para acessar o cofre de chaves existe. Confirme as permissões da identidade gerenciada para acessar o cofre de chaves. Consulte Configurar um nome de domínio personalizado - Cofre de Chaves, anteriormente neste artigo, para obter etapas de configuração detalhadas. Depois que a configuração for restaurada, o certificado de nome do host será atualizado no Gerenciamento de API dentro de 4 horas.