Portal do desenvolvedor do Gerenciamento de API – Perguntas frequentes

E se eu precisar de uma funcionalidade que não tenha suporte no portal?

Você pode abrir uma solicitação de recurso no repositório GitHub ou implementar a funcionalidade ausente por conta própria. Saiba mais sobre a extensibilidade do portal do desenvolvedor.

Posso ter vários portais de desenvolvedor em um serviço de Gerenciamento de API?

Você pode ter um portal gerenciado e vários portais auto-hospedados. O conteúdo de todos os portais é armazenado no mesmo serviço de Gerenciamento de API, portanto, ele será idêntico. Se quiser diferenciar a aparência e a funcionalidade dos portais, poderá auto-hospedá-los com seus próprios widgets personalizados que personalizam dinamicamente as páginas no tempo de execução, por exemplo, com base na URL.

O portal dá suporte a modelos do Azure Resource Manager e/ou é compatível com o Kit de Recursos DevOps de Gerenciamento de API?

Não.

O conteúdo do portal foi salvo com a funcionalidade de backup/restauração no Gerenciamento de API?

Não.

É necessário habilitar a conectividade VNet adicional para as dependências do portal gerenciado?

Na maioria dos casos, não.

Se o serviço de Gerenciamento de API estiver em uma VNet interna, o portal do desenvolvedor só poderá ser acessado de dentro da rede. O nome do host do ponto de extremidade de gerenciamento deve ser resolvido para o VIP interno do serviço do computador usado para acessar a interface administrativa do portal. Verifique se o ponto de extremidade de gerenciamento está registrado no DNS. No caso de erro de configuração, você verá um erro: Unable to start the portal. See if settings are specified correctly in the configuration (...).

Se o serviço do Gerenciamento de API estiver em uma VNet interna e você o estiver acessando por meio do Gateway de Aplicativo da Internet, habilite a conectividade com o portal do desenvolvedor e os pontos de extremidade de gerenciamento do Gerenciamento de API. Talvez seja necessário desabilitar as regras de Firewall de Aplicativo Web. Confira este artigo de documentação para mais detalhes.

Atribuí um domínio personalizado do Gerenciamento de API e o portal publicado não funciona

Depois de atualizar o domínio, você precisará republicar o portal para que as alterações entrem em vigor.

Adicionei um provedor de identidade e não consigo vê-lo no portal

Depois de configurar um provedor de identidade (por exemplo, Azure AD, Azure AD B2C), você precisará republicar o portal para que as alterações entrem em vigor. Verifique se as páginas do portal do desenvolvedor incluem o widget de botões do OAuth.

Configurei a delegação e o portal não a utiliza

Depois de configurar a delegação, você precisará republicar o portal para que as alterações entrem em vigor.

Minhas outras alterações de configuração de Gerenciamento de API não foram propagadas no portal do desenvolvedor

A maioria das alterações de configuração (por exemplo, VNet, credenciais, termos do produto) requer a republicação do portal.

Estou recebendo um erro de CORS ao usar o console interativo

O console interativo faz uma solicitação de API do lado do cliente do navegador. Resolva o problema de CORS adicionando uma política CORS na(s) API(s).

Você pode verificar o status da política CORS na seção Visão geral do portal do serviço de Gerenciamento de API no portal do Azure. Uma caixa de aviso indica uma política ausente ou com erro de configuração.

Observação

Apenas uma política CORS será executada. Se você especificou várias políticas CORS (por exemplo, no nível de API e no nível de todas as APIs), o console interativo poderá não funcionar conforme o esperado.

Screenshot that shows where you can check the status of your CORS policy.

Aplique automaticamente a política CORS clicando no botão Habilitar CORS.

Você também pode habilitar o CORS manualmente.

  1. Selecione o link Aplicar manualmente no nível global para ver o código de política gerado.
  2. Navegue até Todas as APIs na seção APIs do serviço de Gerenciamento de API no portal do Azure.
  3. Selecione o ícone /> na seção >.
  4. Insira a política na seção entrada> do arquivo XML. Verifique se o valor origem> corresponde ao domínio do portal do desenvolvedor.

Observação

Se você aplicar a política CORS no escopo do produto, em vez do escopo de API(s), e a API usar a autenticação de chave de assinatura por meio de um cabeçalho, o console não funcionará.

O navegador emite automaticamente uma solicitação HTTP OPTIONS, que não contém um cabeçalho com a chave de assinatura. Devido à chave de assinatura ausente, o Gerenciamento de API não pode associar a chamada OPTIONS a um produto. Portanto, ela não pode aplicar a política CORS.

Como alternativa, você pode passar a chave de assinatura em um parâmetro de consulta.

O que é o recurso de proxy CORS e quando devo usá-lo?

Selecione a opção Usar proxy CORS na configuração do widget de detalhes da operação de API para rotear as chamadas à API do console interativo por meio do back-end do portal no serviço do Gerenciamento de API. Nessa configuração, você não precisará mais aplicar uma política CORS às suas APIs, e a conectividade com o ponto de extremidade do gateway do computador local não será necessária. Se as APIs forem expostas por meio de um gateway auto-hospedado ou o serviço estiver em uma rede virtual, será necessária a conectividade do serviço de back-end do Gerenciamento de API com o gateway. Se você usar o portal auto-hospedado, especifique o ponto de extremidade de back-end do portal usando a opção backendUrl nos arquivos de configuração. Caso contrário, o portal auto-hospedado não estará ciente da localização do serviço de back-end.

Quais permissões preciso para editar o portal do desenvolvedor?

Se estiver aparecendo o erro Oops. Something went wrong. Please try again later. ao abrir o portal no modo administrativo, talvez você não tenha as permissões necessárias (RBAC do Azure).

Os portais herdados exigiam a permissão Microsoft.ApiManagement/service/getssotoken/action no escopo do serviço (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) para permitir que o administrador do usuário acesse os portais. O novo portal requer a permissão Microsoft.ApiManagement/service/users/token/action no escopo /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.

Você pode usar o script do PowerShell a seguir para criar uma função com a permissão necessária. Lembre-se de alterar o parâmetro <subscription-id>.

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount 
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor" 
$customRole = $contributorRole 
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin" 
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator" 
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action" 
$customRole.IsCustom = $true 
$customRole.AssignableScopes.Clear() 
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>') 
New-AzRoleDefinition -Role $customRole 

Depois que a função é criada, ela pode ser concedida a qualquer usuário da seção IAM (Controle de Acesso) no portal do Azure. A atribuição dessa função a um usuário atribuirá a permissão no escopo do serviço. O usuário poderá gerar tokens SAS em nome de qualquer usuário no serviço. Essa função precisa ser atribuída, pelo menos, ao administrador do serviço. O comando do PowerShell a seguir demonstra como atribuir a função a um usuário user1 no escopo mais baixo para evitar a concessão de permissões desnecessárias ao usuário:

New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1" 

Depois que as permissões tiverem sido concedidas a um usuário, o usuário deverá sair e entrar novamente no portal do Azure para que as novas permissões entrem em vigor.

Estou vendo o erro Unable to start the portal. See if settings are specified correctly (...)

Esse erro é exibido quando uma chamada GET para https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview falha. A chamada é emitida pelo navegador pela interface administrativa do portal.

Se o serviço do Gerenciamento de API estiver em uma VNet, veja a pergunta sobre a conectividade da VNet.

A falha de chamada também pode ser causada por um certificado TLS/SSL, que é atribuído a um domínio personalizado e não é confiável para o navegador. Como mitigação, você poderá remover o domínio personalizado do ponto de extremidade de gerenciamento. O Gerenciamento de API recorrerá ao ponto de extremidade padrão com um certificado confiável.

Qual o suporte do navegador para o portal?

Navegador Com suporte
Apple Safari Sim1
Google Chrome Sim1
Microsoft Edge Sim1
Microsoft Internet Explorer Não
Mozilla Firefox Sim1

1 Com suporte nas duas versões de produção mais recentes.

O desenvolvimento local do meu portal auto-hospedado não está mais funcionando

Se a sua versão local do portal do desenvolvedor não puder salvar nem recuperar informações da conta de armazenamento ou da instância do Gerenciamento de API, os tokens SAS poderão ter expirado. Corrija isso gerando tokens. Para obter instruções, veja o tutorial sobre como auto-hospedar o portal do desenvolvedor.

Como fazer para desabilitar a inscrição no portal do desenvolvedor?

Se você não precisar da funcionalidade de inscrição habilitada por padrão no portal do desenvolvedor, desabilite-a usando estas etapas:

  1. No portal do Azure, navegue até a instância do Gerenciamento de API.

  2. Em Portal do desenvolvedor, no menu, selecione Identidades.

  3. Exclua cada provedor de identidade que aparece na lista. Escolha cada provedor, selecione o menu de contexto ( ... ) e selecione Excluir.

    Delete identity providers

  4. Navegue até a interface administrativa do portal do desenvolvedor.

  5. Remova os links de Inscrição e os itens de navegação no conteúdo do portal. Para obter informações sobre como personalizar o conteúdo do portal, confira Tutorial: Acessar e personalizar o portal do desenvolvedor.

    Delete navigation item

  6. Modifique o conteúdo da página Inscrever-se para remover os campos usados para inserir dados de identidade, caso os usuários naveguem diretamente até ela.

    Como opção, exclua a página Inscrição. Atualmente, você usa as APIs REST contentItem para listar e excluir essa página.

  7. Salve as suas alterações e republique o portal.

Como posso remover o conteúdo do portal do desenvolvedor provisionado no meu serviço do Gerenciamento de API?

Forneça os parâmetros necessários no script scripts.v3/cleanup.bat no scripts.v3/cleanup.bat do portal do desenvolvedor e execute o script

cd scripts.v3
.\cleanup.bat
cd ..

Como fazer para habilitar a autenticação de SSO (logon único) no portal do desenvolvedor auto-hospedado?

Entre outros métodos de autenticação, o portal do desenvolvedor dá suporte ao SSO (logon único). Para se autenticar com esse método, você precisará fazer uma chamada a /signin-sso com o token no parâmetro de consulta:

https://contoso.com/signin-sso?token=[user-specific token]

Gerar tokens de usuário

Você pode gerar tokens específicos do usuário (incluindo tokens de administrador) usando a operação Obter Token de Acesso Compartilhado da API REST do Gerenciamento de API.

Observação

O token precisa ser codificado por URL.

Próximas etapas

Saiba mais sobre o novo portal do desenvolvedor:

Acesse outros recursos: