Visão geral do portal do desenvolvedor
APLICA-SE A: Desenvolvedor | Básico | Básico v2 | Standard | Standard v2 | Premium
O portal do desenvolvedor do Gerenciamento de API é um site gerado de modo automático e totalmente personalizável com a documentação das suas APIs. É aqui que os consumidores de APIs podem descobrir suas APIs, aprender como usá-las, solicitar acesso e experimentá-las.
Este artigo apresenta os recursos do portal do desenvolvedor, os tipos de conteúdo que ele apresenta e as opções para gerenciá-lo e estendê-lo a seus usuários e cenários específicos.
Observação
Recentemente, aprimoramos a interface do editor do portal para aumentar sua produtividade e aprimorar as interações com seus recursos e ferramentas favoritos. Também reprojetamos os widgets de detalhes da API e do produto para elevar a experiência do portal para os visitantes.
APLICA-SE A: Desenvolvedor | Básico | Standard | Premium
Conceitos de arquitetura do portal do desenvolvedor
Os componentes do portal podem ser divididos logicamente em duas categorias: código e conteúdo.
Código
O código é mantido no repositório GitHub do portal do desenvolvedor do Gerenciamento de API e inclui:
- Widgets: representam elementos visuais e combinam HTML, JavaScript, capacidade de estilo, configurações e mapeamento de conteúdo. Entre os exemplos estão uma imagem, um parágrafo de texto, um formulário, uma lista de APIs etc.
- Definições de estilo: especificam como os widgets podem ser estilizados
- Mecanismo: gera páginas da Web estáticas do conteúdo do portal e é escrito em JavaScript
- Editor visual: permite a experiência de criação e personalização no navegador
Sumário
O conteúdo está dividido em duas subcategorias: conteúdo do portal e dados do Gerenciamento de API.
O conteúdo do portal é específico do site do portal e inclui:
Páginas: por exemplo, página de aterrissagem, tutoriais de API e postagens no blog
Mídia: imagens, animações e outros tipos de conteúdo baseado em arquivo
Layouts: modelos que têm uma URL correspondente e definem como as páginas são exibidas.
Estilos: valores para definições de estilo, como fontes, cores e bordas
Configurações: configurações como favicon e metadados do site
O conteúdo do portal, exceto para mídia, é expresso como documentos JSON.
dados de Gerenciamento de API: inclui entidades como APIs, Operações, Produtos e Assinaturas gerenciadas em sua instância de Gerenciamento de API.
Personalizar e estilizar o portal
Pronto para uso, o portal do desenvolvedor já está preenchido com suas APIs e produtos publicados e pronto para ser personalizado conforme suas necessidades. Como editor de API, você usa a interface administrativa do portal do desenvolvedor para personalizar a aparência e a funcionalidade do portal do desenvolvedor.
Se você estiver acessando o portal pela primeira vez, ele inclui páginas com espaço reservado, conteúdo e menus de navegação. O conteúdo com espaço reservado foi projetado para apresentar as funcionalidades do portal e minimizar as personalizações necessárias do seu portal.
Para obter um passo a passo sobre como personalizar e publicar o portal do desenvolvedor, confira Tutorial: Acessar e personalizar o portal do desenvolvedor.
Importante
- O acesso ao portal do desenvolvedor por fornecedores e consumidores de API requer conectividade de rede com o ponto de extremidade do portal do desenvolvedor (padrão:
https://<apim-instance-name>.portal.azure-api.net) e o ponto de extremidade de gerenciamento da instância de Gerenciamento de API (padrão:https://<apim-instance-name>.management.azure-api.net). - A publicação do portal do desenvolvedor requer conectividade adicional com o armazenamento de blobs gerenciado pelo Gerenciamento de API na região Oeste dos EUA.
- Se a instância de Gerenciamento de API for implantada em uma VNet, os nomes de host do portal do desenvolvedor e do ponto de extremidade de gerenciamento devem estar resolvidos corretamente e a conectividade com as dependências necessárias do portal do desenvolvedor deve estar habilitada. Saiba mais.
Editor visual
A interface administrativa do portal do desenvolvedor fornece um editor visual para os editores personalizarem o conteúdo e o estilo do portal. Usando o editor visual, você pode adicionar, remover e reorganizar páginas, seções e widgets. Você também pode alterar o estilo dos elementos do portal, como fontes, cores e espaçamento.
Como administrador, você pode personalizar o conteúdo do portal usando o editor visual.
Use as opções do menu à esquerda para criar ou modificar páginas, mídia, layouts, menus, estilos ou configurações de site.
Na parte superior, alterne entre os visores (para telas de tamanhos diferentes) ou exiba os elementos do portal visíveis para usuários em grupos diferentes. Por exemplo, talvez seja conveniente exibir determinadas páginas apenas para grupos associados a produtos específicos ou para usuários que possam acessar APIs específicas.
Além disso, salve ou desfaça as alterações feitas ou publique o site.
Selecione os elementos de texto e título existentes para editar e formatar o conteúdo.
Adicione uma seção a uma página passando o mouse sobre uma área em branco e selecione um ícone azul com um sinal de adição. Escolha entre vários layouts de seção.
Adicione um widget (por exemplo, texto, imagem, widget personalizado ou lista de APIs) passando o mouse sobre uma área em branco e, em seguida, selecione um ícone cinza com um sinal de adição.
Reorganize os itens em uma página por arrastar e soltar.
Layouts e páginas
Os layouts definem como as páginas são exibidas. Por exemplo, no conteúdo padrão, há dois layouts: um se aplica à home page e o outro, a todas as páginas restantes. Você pode modificar esses layouts e adicionar mais layouts conforme suas necessidades.
Um layout é aplicado a uma página por meio da correspondência do modelo de URL à URL da página. Por exemplo, um layout com um modelo de URL /wiki/* será aplicado a cada página com o segmento /wiki/ na URL: /wiki/getting-started, /wiki/styles etc.
Na imagem a seguir, o conteúdo que pertence ao layout é descrito em azul, enquanto o conteúdo específico da página é descrito em vermelho.
O conteúdo pré-provisionado no portal do desenvolvedor mostra páginas com os recursos mais usados. Você pode modificar o conteúdo dessas páginas ou adicionar novas para atender às suas necessidades.
Observação
Devido a considerações de integração, as seguintes páginas não podem ser removidas nem movidas para outra URL: /404, /500, /captcha, /change-password, /config.json, /confirm/invitation, /confirm-v2/identities/basic/signup, /confirm-v2/password, /internal-status-0123456789abcdef, /publish, /signin, /signin-sso e /signup.
Estilos
O painel Estilos foi criado pensando nos designers. Use estilos para gerenciar e personalizar todos os elementos visuais do seu portal, como fontes usadas em títulos e menus e cores de botão. O estilo é hierárquico: muitos elementos herdam propriedades de outros elementos. Por exemplo, os elementos de botão usam cores para texto e tela de fundo. Para alterar a cor de um botão, você precisa alterar a variante da cor original.
Para editar uma variante, selecione-a e escolha Editar estilo nas opções exibidas sobre ela. Depois de fazer as alterações na janela pop-up, feche-a.
Estender funcionalidade do portal
Em alguns casos, talvez você precise de funcionalidade além das opções de personalização e estilo fornecidas no portal do desenvolvedor gerenciado. Se precisar implementar a lógica personalizada, que não tem suporte pronto para uso, você terá várias opções:
- Adicione um HTML personalizado diretamente por meio de um widget do portal do desenvolvedor projetado para pequenas personalizações - por exemplo, adicione um HTML a um formulário ou insira um player de vídeo. O código personalizado é renderizado em um quadro embutido (iframe).
- Crie e carregue um widget personalizado para desenvolver e adicionar recursos de portal personalizados mais complexos.
- Hospede o portal automaticamente, somente se você precisar fazer modificações no núcleo da base de código do portal do desenvolvedor. Essa opção requer configuração avançada. A assistência do suporte do Azure é limitada apenas à configuração básica de portais auto-hospedados.
Observação
Como a base de código do portal do desenvolvedor de Gerenciamento de API é mantida no GitHub, você pode abrir problemas e fazer solicitações de pull para a equipe de Gerenciamento de API mesclar novas funcionalidades a qualquer momento.
Controlar o acesso ao conteúdo do portal
O portal do desenvolvedor é sincronizado com sua instância de Gerenciamento de API para exibir conteúdo como APIs, operações, produtos, assinaturas e perfis de usuário. As APIs e os produtos devem estar em um estado publicado para serem exibidos no portal do desenvolvedor.
Visibilidade e acesso do conteúdo
No Gerenciamento de API, grupos de usuários são usados para gerenciar a visibilidade dos produtos e as APIs associadas para os desenvolvedores. Além de usar grupos internos, você pode criar grupos personalizados conforme suas necessidades. Os produtos ficam visíveis primeiro para os grupos, e depois os desenvolvedores nesses grupos podem ver e assinar os produtos associados aos grupos.
Você também pode controlar como outro conteúdo do portal (ex.: páginas e seções) será exibido para usuários diferentes, com base na identidade deles. Por exemplo, talvez você queira exibir determinadas páginas somente para usuários que têm acesso a um produto ou API específico. Ou faça com que uma seção de uma página apareça apenas para determinados grupos de usuários. O portal do desenvolvedor tem controles internos para essas necessidades.
Observação
Os controles de visibilidade e acesso têm suporte apenas no portal do desenvolvedor gerenciado. Eles não têm suporte no portal auto-hospedado.
Ao adicionar uma página ou editar as configurações de uma página existente, faça uma seleção em Acesso para controlar os usuários ou grupos que podem ver a página
Dica
Para editar as configurações de uma página existente, selecione o ícone de engrenagem ao lado do nome da página na guia Páginas.
Ao selecionar o conteúdo da página, como uma seção dela, menu ou botão para edição, selecione o ícone Alterar acesso para controlar os usuários ou grupos que podem ver o elemento na página.
Você pode alterar a visibilidade do conteúdo da página a seguir: seções, menus, botões e entrada para autorização do OAuth.
Arquivos de mídia, como imagens em uma página, herdam a visibilidade dos elementos que os contêm.
Quando um usuário visita o portal do desenvolvedor com controles de visibilidade e acesso aplicados:
O portal do desenvolvedor oculta automaticamente botões ou itens de navegação que apontam para páginas às quais um usuário não tem acesso.
Uma tentativa de um usuário de acessar uma página à qual ele não está autorizado resulta em um erro 404 Não encontrado.
Dica
Usando a interface administrativa, você pode visualizar páginas como um usuário associado a qualquer grupo interno ou personalizado selecionando Exibir como no menu na parte superior.
Política de segurança de conteúdo
Você pode habilitar uma política de segurança de conteúdo para adicionar uma camada de segurança ao portal do desenvolvedor e ajudar a atenuar determinados tipos de ataques, incluindo cross-site scripting e injeção de dados. Com uma política de segurança de conteúdo, o portal do desenvolvedor no navegador só carregará recursos de locais confiáveis que você especificar, como seu site corporativo ou outros domínios confiáveis.
Para habilitar uma política de segurança de conteúdo:
- No portal do Azure, navegue até a instância do Gerenciamento de API.
- No menu à esquerda, em Portal do desenvolvedor, escolha Configurações do portal.
- Na guia Política de segurança de conteúdo, selecione Habilitada.
- Em Origens permitidas, adicione um ou mais nomes de host que especifiquem locais confiáveis dos quais o portal do desenvolvedor possa carregar recursos. Você também pode especificar um caractere curinga para permitir todos os subdomínios de um domínio. Por exemplo,
*.contoso.compermite todos os subdomínios decontoso.com. - Selecione Salvar.
Console de teste interativo
O portal do desenvolvedor fornece uma funcionalidade "Experimente" nas páginas de referência da API para que os visitantes do portal possam testar suas APIs diretamente por meio de um console interativo.
O console de teste dá suporte a APIs com modelos de autorização diferentes. Por exemplo, APIs que não exigem autorização ou que exigem uma chave de assinatura ou autorização OAuth 2.0. Neste último caso, você pode configurar o console de teste para gerar um token OAuth válido em nome do usuário do console de teste. Para obter mais informações, consulte Como autorizar o console de teste do portal do desenvolvedor configurando a autorização de usuário do OAuth 2.0.
Importante
Para que os visitantes do seu portal possam testar as APIs por meio do console interativo interno, habilite uma política de CORS (compartilhamento de recursos entre origens) nas suas APIs. Para obter detalhes, consulte Habilitar CORS para console interativo no portal do desenvolvedor de Gerenciamento de API.
Gerenciar credenciais do usuário
Por padrão, o portal do desenvolvedor habilita o acesso anônimo. Isso significa que qualquer pessoa pode exibir o portal e seu conteúdo sem entrar, embora o acesso a determinados conteúdos e funcionalidades, como usar o console de teste, possa ser restrito. Você pode habilitar uma configuração de site do portal do desenvolvedor para exigir que os usuários entrem para acessá-lo.
O portal dá suporte a várias opções de inscrição e entrada do usuário:
Autenticação básica para desenvolvedores entrarem com credenciais de contas de usuário do Gerenciamento de API. Os desenvolvedores podem se criar uma conta diretamente por meio do portal ou você pode criar contas para eles.
Dependendo dos seus cenários, restrinja o acesso ao portal exigindo que os usuários se inscrevam ou entrem com uma conta do Microsoft Entra ID ou do Azure AD B2C.
Se você já gerencia as credenciais do desenvolvedor por meio de um site existente, delegue a autenticação em vez de usar a autenticação interna do portal do desenvolvedor.
Saiba mais sobre as opções de proteção das credenciais do usuário no portal do desenvolvedor.
Relatórios para usuários
O portal do desenvolvedor gera relatórios para os usuários autenticados verem o uso individual da API, a transferência de dados e os tempos de resposta, incluindo o uso agregado por produtos e assinaturas específicos. Os usuários autenticados podem ver os relatórios selecionando Relatórios no menu de navegação padrão. Os usuários podem filtrar os relatórios por intervalo de tempo, até os últimos 90 dias.
Observação
Os relatórios no portal do desenvolvedor mostram apenas os dados do usuário autenticado. Os editores e administradores de API podem acessar dados de uso de todos os usuários da instância de Gerenciamento de API. Por exemplo, configurando recursos de monitoramento, como Azure Application Insights no portal.
Salvar e publicar conteúdo do site
Depois de atualizar o conteúdo ou a configuração do portal do desenvolvedor, você precisará salvar e publicar as alterações para disponibilizá-las para os visitantes do portal. O portal do desenvolvedor mantém um registro do conteúdo publicado e você pode reverter para uma revisão anterior do portal quando necessário.
Salvar as alterações
Sempre que você fizer uma alteração no portal, precisará salvá-la manualmente selecionando o botão Salvar no menu, na parte superior, ou selecionando [CTRL] + [S]. Se precisar, você poderá Desfazer as últimas alterações salvas. Enquanto as alterações salvas não forem publicadas, somente você poderá vê-las.
Observação
O portal do desenvolvedor gerenciado recebe e aplica atualizações de software automaticamente. As alterações salvas, mas não publicadas no portal do desenvolvedor, permanecem nesse estado durante uma atualização.
Publicar o portal
Para disponibilizar seu portal e as últimas alterações dele para os visitantes, você precisará publicá-lo. Publique o portal na interface administrativa dele ou no portal do Azure.
Importante
Você precisa publicar o portal para poder expor alterações no conteúdo ou estilo dele. O portal também precisará ser publicado novamente após alterações de configuração do serviço Gerenciamento de API que o afetem. Por exemplo, publique o portal novamente depois de atribuir um domínio personalizado, atualizar os provedores de identidade, definir a delegação ou especificar a entrada e os termos do produto.
Publicação por meio da interface administrativa
Lembre-se de salvar as alterações selecionando o botão Salvar.
No menu na parte superior, selecione Publicar site. Esta operação pode levar alguns minutos.
Publicação por meio do portal do Azure
No portal do Azure, navegue até a instância do Gerenciamento de API.
No menu à esquerda, em Portal do desenvolvedor, escolha Visão geral do portal.
Na janela Visão geral do portal, selecione Publicar.
Restaurar uma revisão anterior do portal
Sempre que você publica o portal do desenvolvedor, uma revisão do portal correspondente é salva. Você pode republicar uma revisão anterior do portal a qualquer momento. Por exemplo, talvez você queira reverter uma alteração introduzida quando publicou o portal pela última vez.
Observação
As atualizações de software do portal do desenvolvedor são aplicadas automaticamente quando você restaura uma revisão. As alterações salvas, mas não publicadas na interface administrativa, permanecem nesse estado quando você publica uma revisão.
Para restaurar uma revisão anterior do portal:
- No portal do Azure, navegue até a instância do Gerenciamento de API.
- No menu à esquerda, em Portal do desenvolvedor, escolha Visão geral do portal.
- Na guia Revisões, selecione o menu de contexto (...) da revisão que você deseja restaurar e selecione Tornar atual e publicar.
Redefinir o portal
Para descartar todas as alterações feitas no portal do desenvolvedor, restaure o estado inicial do site. A restauração do portal exclui todas as alterações feitas nas páginas do portal do desenvolvedor, layouts, personalizações e mídia carregada.
Observação
A restauração do portal do desenvolvedor não exclui a versão publicada dele.
Para restaurar o portal do desenvolvedor:
- Na interface administrativa, no menu à esquerda do editor visual, selecione Configurações.
- Na guia Avançado, selecione Sim, restaure o estado padrão do site.
- Selecione Salvar.
Conteúdo relacionado
Saiba mais sobre o portal do desenvolvedor:
- Acessar e personalizar o portal do desenvolvedor gerenciado
- Estender a funcionalidade do portal do desenvolvedor gerenciado
- Configurar a versão auto-hospedada do portal
Acesse outros recursos: