Hospedar automaticamente o portal do desenvolvedor de Gerenciamento de API

Artigo
03/29/2024

APLICA-SE A: Desenvolvedor | Básico | Standard | Premium

Este tutorial descreve como hospedar automaticamente o portal do desenvolvedor de Gerenciamento de API. A auto-hospedagem é uma das diversas opções para estender a funcionalidade do portal do desenvolvedor. Por exemplo, você pode hospedar vários portais de hospedagem múltipla para a instância de Gerenciamento de API, com recursos diferentes. Ao auto-hospedar o portal, você se torna responsável pela manutenção e pelas atualizações.

Importante

Considere a auto-hospedagem do portal do desenvolvedor somente quando for necessário modificar o núcleo da base de código do portal do desenvolvedor. Essa opção requer configuração avançada, incluindo:

Implantação em uma plataforma de hospedagem, opcionalmente apoiada por uma solução como CDN para aumentar a disponibilidade e o desempenho
Manutenção e gerenciamento da infraestrutura de hospedagem
Atualizações manuais, inclusive para patches de segurança, que podem exigir que você resolva conflitos de código ao atualizar a base de código

Observação

O portal auto-hospedado não dá suporte à visibilidade e aos controles de acesso disponíveis no portal do desenvolvedor gerenciado.

Se você já carregou ou modificou arquivos de mídia no portal gerenciado, consulte Mover de gerenciado para auto-hospedado, posteriormente neste artigo.

Pré-requisitos

Para configurar um ambiente de desenvolvimento local, você precisa de:

Uma instância do Serviço de Gerenciamento de API. Se você não tiver um, consulte Início rápido – Criar uma instância de Gerenciamento de API do Azure.
Uma conta de armazenamento do Azure com o recurso sites estáticos habilitado. Consulte Criar uma conta de armazenamento.
Git no seu computador. Instale-o seguindo este tutorial do Git.
Node.js (versão LTS, v10.15.0 ou posterior) e npm em seu computador. Consulte Baixando e instalando Node.js e npm.
CLI do Azure. Siga as etapas de instalação da CLI do Azure.

Etapa 1: configurar o ambiente local

Para configurar seu ambiente local, você precisará clonar o repositório, alternar para a versão mais recente do portal do desenvolvedor e instalar os pacotes do npm.

Clone o repositório api-management-developer-portal no GitHub:

git clone https://github.com/Azure/api-management-developer-portal.git

Vá até a sua cópia local da reposição:
```
cd api-management-developer-portal
```
Confira a versão mais recente do portal.

Antes de executar o código a seguir, verifique a marca de versão atual na seção Versões do repositório e substitua <current-release-tag> o valor pela última marca de versão.
```
git checkout <current-release-tag>
```
Instale todos os pacotes npm disponíveis:
```
npm install
```

Dica

Sempre use a versão mais recente do portal e mantenha seu portal bifurcado atualizado. Os engenheiros de software usam a ramificação master desse repositório para fins de desenvolvimento diário. Ele tem versões instáveis do software.

Etapa 2: configurar arquivos JSON, site estático e configurações de CORS

O portal do desenvolvedor exige a API REST do Gerenciamento de API para gerenciar o conteúdo.

Arquivo config.design.json

Vá para a pasta src e abra o arquivo config.design.json.

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

Configurar o arquivo:

No valor managementApiUrl, substitua <service-name> pelo nome da sua instância do serviço de Gerenciamento de API. Se você configurou um domínio personalizado, use-o em vez disso (por exemplo, https://management.contoso.com).
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...
```
Crie manualmente um token SAS para habilitar o acesso direto à API REST à sua instância de Gerenciamento de API.
Copie o token gerado e cole-o como o valor managementApiAccessToken.
No valor backendUrl, substitua <service-name> pelo nome da sua instância do serviço de Gerenciamento de API. Se você configurou um domínio personalizado, use-o em vez disso (por exemplo, https://portal.contoso.com).
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```
Para habilitar o CAPTCHA no portal do desenvolvedor, confira "useHipCaptcha": true. Defina as configurações do CORS para back-end do portal do desenvolvedor.
Na integration, em googleFonts, opcionalmente, defina apiKey como uma chave de API do Google que permite o acesso à API do Desenvolvedor de fontes Web. Essa chave só será necessária se você quiser adicionar fontes do Google na seção Estilos do editor do portal do desenvolvedor.

Se você ainda não tiver uma chave, é possível configurar uma usando o console do Google Cloud. Siga estas etapas:
1. Abra o console do Google Cloud.
2. Verifique se a API do Desenvolvedor de fontes Web está habilitada. Se ela não estiver, habilite-a.
3. Selecione Criar credenciais de >chave de API.
4. Na caixa de diálogo aberta, copie a chave gerada e cole-a como o valor de apiKey no arquivo config.design.json.
5. Selecione Editar chave de API para abrir o editor de chaves.
6. No editor, em Restrições de API, selecione Restringir chave. Na lista suspensa, selecione API do Desenvolvedor de fontes Web.
7. Selecione Salvar.

Arquivo config.publish.json

Vá para a pasta src e abra o arquivo config.publish.json.

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Configurar o arquivo:

Copie e cole os valores managementApiUrl e managementApiAccessToken do arquivo de configuração anterior.
Para habilitar o CAPTCHA no portal do desenvolvedor, confira "useHipCaptcha": true. Defina as configurações do CORS para back-end do portal do desenvolvedor.

Arquivo config.runtime.json

Vá para a pasta src e abra o arquivo config.runtime.json.

{
  "environment": "runtime",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "backendUrl": "https://<service-name>.developer.azure-api.net"
}

Configurar o arquivo:

Copie e cole o valor managementApiUrl do arquivo de configuração anterior.
No valor backendUrl, substitua <service-name> pelo nome da sua instância do serviço de Gerenciamento de API. Se você tiver configurado um domínio personalizado, use-o em vez disso (por exemplo, https://portal.contoso.com).
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```

Configurar o site estático

Configure o recurso de site estático na conta de armazenamento fornecendo rotas para as páginas de índice e erro:

Acesse a conta de armazenamento no portal do Azure e selecione site estático no menu à esquerda.
Na página Site estático, selecione Habilitado.
No campo Nome do índice do documento, insira index.html.
No campo Caminho do índice do documento, insira 404/index.html.
Selecione Salvar.

Definir as configurações do CORS para a conta de armazenamento

Definir as configurações do CORS (Compartilhamento de Recursos entre Origens) para a conta de armazenamento:

Acesse a conta de armazenamento no portal do Azure e selecione CORS no menu à esquerda.
Na guia Serviço Blob, configure as seguintes regras:

Regra Valor

Origens permitidas *

Métodos permitidos Selecione todos os verbos HTTP.

Cabeçalhos permitidos *

Cabeçalhos expostos *

Idade máxima 0
Selecione Salvar.

Regra	Valor
Origens permitidas	*
Métodos permitidos	Selecione todos os verbos HTTP.
Cabeçalhos permitidos	*
Cabeçalhos expostos	*
Idade máxima	0

Defina as configurações do CORS para back-end do portal do desenvolvedor

Defina as configurações do CORS para back-end do portal do desenvolvedor a fim de permitir solicitações originadas por meio do portal do desenvolvedor auto-hospedado. O portal do desenvolvedor auto-hospedado depende do ponto de extremidade de back-end do portal do desenvolvedor (definido em backendUrl nos arquivos de configuração do portal) para habilitar vários recursos, incluindo:

Verificação de CAPTCHA
Autorização OAuth 2.0 no console de teste
Delegação de autenticação de usuário e assinatura de produto

Para adicionar as configurações do CORS:

Acesse a instância do Gerenciamento de API no portal do Azure e selecione Portal do desenvolvedor>Configurações do portal no menu à esquerda.
Na guia Configuração do portal auto-hospedado, adicione um ou mais valores de domínio de Origem. Por exemplo:
- O domínio em que o portal auto-hospedado está hospedado, como https://www.contoso.com
- localhost para desenvolvimento local (se aplicável), como http://localhost:8080 ou https://localhost:8080
Selecione Salvar.

Etapa 3: executar o portal

Agora você pode criar e executar uma instância do portal local no modo de desenvolvimento. No modo de desenvolvimento, todas as otimizações são desativadas, e os mapas de origem são ativados.

Execute o comando a seguir:

npm start

Após um curto período, o navegador padrão é aberto automaticamente com sua instância local do portal do desenvolvedor. O endereço padrão é http://localhost:8080, mas a porta poderá ser alterada se 8080 já estiver ocupada. As alterações na base de código do projeto disparam uma recompilação e atualizam a janela do navegador.

Etapa 4: editar por meio do editor visual

Use o editor visual para executar estas tarefas:

Personalizar o portal
Conteúdo do autor
Organizar a estrutura do site
Estilizar a aparência

Consulte Tutorial: acessar e personalizar o portal do desenvolvedor. Ele aborda os conceitos básicos da interface do usuário administrativo e lista as alterações recomendadas no conteúdo padrão. Salve todas as alterações no ambiente local e pressione Ctrl+C para fechá-lo.

Etapa 5: publicar localmente

Os dados do portal se originam na forma de objetos de tipo forte. O comando a seguir converte-os em arquivos estáticos e coloca a saída no diretório ./dist/website:

npm run publish

Etapa 6: carregar arquivos estáticos em um blob

Use a CLI do Azure para carregar os arquivos estáticos gerados localmente em um blob e verifique se os visitantes podem acessá-los:

Abra o prompt de comando do Windows, o PowerShell ou outro Shell de comando.
Execute o comando da CLI do Azure a seguir.

Substitua <account-connection-string> pela cadeia de conexão da conta de armazenamento. Você pode obtê-lo na seção de Chaves de acesso da sua conta de armazenamento.
```
az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>
```

Etapa 7: ir para seu site

Seu site agora está ativo sob o nome de host especificado nas propriedades do Armazenamento do Azure (Ponto de extremidade primário em sites estáticos).

Etapa 8: alterar modelos de notificação de Gerenciamento de API

Substitua a URL do portal do desenvolvedor nos modelos de notificação de Gerenciamento de API para apontar para o portal de hospedagem interna. Consulte Como configurar notificações e modelos de email no Gerenciamento de API do Azure.

Em particular, realize as seguintes alterações para os modelos padrão:

Observação

Os valores nas seções atualizadas a seguir pressupõem que você está hospedando o portal em https://portal.contoso.com/.

Confirmação de alteração de email

Atualize a URL do portal do desenvolvedor no modelo de notificação de Confirmação de alteração de email:

Conteúdo original

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Updated

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Confirmação da conta nova de desenvolvedor

Atualize a URL do portal do desenvolvedor no modelo de notificação de Confirmação da conta nova de desenvolvedor:

Conteúdo original

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Updated

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Convidar usuário

Atualize a URL do portal do desenvolvedor no modelo de notificação de Convidar usuário:

Conteúdo original

<a href="$ConfirmUrl">$ConfirmUrl</a>

Updated

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Nova assinatura ativada

Atualize a URL do portal do desenvolvedor no modelo de notificação de Nova assinatura ativada:

Conteúdo original

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Updated

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Conteúdo original

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Updated

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Conteúdo original

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Updated

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Conteúdo original

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

Updated

<!--Remove the entire block of HTML code above.-->

Confirmação de alteração de senha

Atualize a URL do portal do desenvolvedor no modelo de notificação de Confirmação de alteração de senha:

Conteúdo original

<a href="$DevPortalUrl">$DevPortalUrl</a>

Updated

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Todos os modelos

Atualize a URL do portal do desenvolvedor em qualquer modelo que tenha um link no rodapé:

Conteúdo original

<a href="$DevPortalUrl">$DevPortalUrl</a>

Updated

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

Mover do portal do desenvolvedor gerenciado para o auto-hospedado

Ao longo do tempo, os requisitos de negócios podem ser alterados. Você pode terminar em uma situação em que a versão gerenciada do portal do desenvolvedor do Gerenciamento de API não atenda mais às suas necessidades. Por exemplo, um novo requisito pode forçá-lo a criar um widget personalizado que se integre a um provedor de dados de terceiros. Diferentemente da versão gerenciada, a versão hospedada internamente do portal oferece flexibilidade e extensibilidade completas.

Processo de transição

Você pode fazer a transição da versão gerenciada para uma versão hospedada internamente na mesma instância do serviço de Gerenciamento de API. O processo preserva as modificações que você realizou na versão gerenciada do Portal. Certifique-se de fazer backup do conteúdo do portal com antecedência. Você pode encontrar o script de backup na pasta scripts do repositório GitHub do portal do desenvolvedor de Gerenciamento de API.

O processo de conversão é quase idêntico à configuração de um portal genérico auto-hospedado, conforme mostrado nas etapas anteriores neste artigo. Há uma exceção na etapa de configuração. A conta de armazenamento no arquivo config.design.json precisa ser a mesma que a conta de armazenamento da versão gerenciada do Portal. Consulte Tutorial: usar uma identidade atribuída pelo sistema de VM do Linux para acessar o Armazenamento do Azure por meio de uma credencial SAS para obter instruções sobre como recuperar a URL da SAS.

Dica

É recomendável usar uma conta de armazenamento separada no arquivo config.publish.json. Essa abordagem oferece mais controle e simplifica o gerenciamento do serviço de hospedagem do seu portal.

Próximas etapas

Saiba mais sobre Abordagens alternativas para hospedagem interna

Hospedar automaticamente o portal do desenvolvedor de Gerenciamento de API

Pré-requisitos

Etapa 1: configurar o ambiente local

Etapa 2: configurar arquivos JSON, site estático e configurações de CORS

Arquivo config.design.json

Arquivo config.publish.json

Arquivo config.runtime.json

Configurar o site estático

Definir as configurações do CORS para a conta de armazenamento

Defina as configurações do CORS para back-end do portal do desenvolvedor

Etapa 3: executar o portal

Etapa 4: editar por meio do editor visual

Etapa 5: publicar localmente

Etapa 6: carregar arquivos estáticos em um blob

Etapa 7: ir para seu site

Etapa 8: alterar modelos de notificação de Gerenciamento de API

Confirmação de alteração de email

Confirmação da conta nova de desenvolvedor

Convidar usuário

Nova assinatura ativada

Confirmação de alteração de senha

Todos os modelos

Mover do portal do desenvolvedor gerenciado para o auto-hospedado

Processo de transição

Próximas etapas

Recursos adicionais