Hospedar automaticamente o portal do desenvolvedor de Gerenciamento de API

Este tutorial descreve como hospedar automaticamente o portal do desenvolvedor de Gerenciamento de API. A hospedagem interna oferece flexibilidade para estender o portal do desenvolvedor com lógica personalizada e widgets que personalizam dinamicamente as páginas em runtime. 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 atualizações.

As etapas a seguir mostram como configurar o ambiente de desenvolvimento local, executar alterações no portal do desenvolvedor e publicá-las e implantá-las em uma conta de armazenamento do Azure.

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

Disponibilidade

Importante

Este recurso está disponível nas camadas Premium, Standard, Básico e Desenvolvedor do Gerenciamento de API.

Pré-requisitos

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

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.

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

    git clone https://github.com/Azure/api-management-developer-portal.git
    
  2. Vá até a sua cópia local da reposição:

    cd api-management-developer-portal
    
  3. 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>
    
  4. 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
}

Configurar o arquivo:

  1. 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"
    ...
    
  2. Crie manualmente um token SAS para habilitar o acesso direto à API REST à sua instância de Gerenciamento de API.

  3. Copie o token gerado e cole-o como o valor managementApiAccessToken.

  4. 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"
    ...
    
  5. Se você quiser habilitar o CAPTCHA no portal do desenvolvedor, consulte Habilitar captcha.

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:

  1. Copie e cole os valores managementApiUrl e managementApiAccessToken do arquivo de configuração anterior.

  2. Se você quiser habilitar o CAPTCHA no portal do desenvolvedor, consulte Habilitar captcha.

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:

  1. Copie e cole o valor managementApiUrl do arquivo de configuração anterior.

  2. 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:

  1. Acesse a conta de armazenamento no portal do Azure e selecione site estático no menu à esquerda.

  2. Na página Site estático, selecione Habilitado.

  3. No campo Nome do índice do documento, insira index.html.

  4. No campo Caminho do índice do documento, insira 404/index.html.

  5. Selecione Salvar.

Definir as configurações de CORS

Configurar as definições de CORS (Compartilhamento de Recursos entre Origens):

  1. Acesse a conta de armazenamento no portal do Azure e selecione CORS no menu à esquerda.

  2. 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
  3. 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 vão disparar uma recompilação e atualizar 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:

  1. Abra o prompt de comando do Windows, o PowerShell ou outro Shell de comando.

  2. 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.

Habilitar CAPTCHA

Ao configurar o portal auto-hospedado, você pode ter desabilitado o CAPTCHA por meio da configuração useHipCaptcha. A comunicação com o CAPTCHA ocorre por um ponto de extremidade, o que permite que o CORS (compartilhamento de recursos entre origens) aconteça apenas no nome de host do portal do desenvolvedor gerenciado. Se o portal do desenvolvedor for auto-hospedado, ele usará um nome de host diferente e o CAPTCHA não permitirá a comunicação.

Atualizar os arquivos de configuração JSON

Para habilitar o CAPTCHA em seu portal de hospedagem interna:

  1. Atribua um domínio personalizado (por exemplo, api.contoso.com) ao ponto de extremidade do Portal do desenvolvedor do serviço de Gerenciamento de API.

    Esse domínio se aplica à versão gerenciada do seu portal e ao ponto de extremidade CAPTCHA. Para obter as etapas, consulte Configurar um nome de domínio personalizado para a sua instância de Gerenciamento de API do Azure.

  2. Vá para a pasta src no ambiente local do portal de auto-hospedagem.

  3. Atualize os arquivos de configuração json:

    Arquivo Novo valor Observação
    config.design.json "backendUrl": "https://<custom-domain>" Substitua <custom-domain> pelo domínio personalizado que você configurou na primeira etapa.
    "useHipCaptcha": true Altere o valor para true
    config.publish.json "backendUrl": "https://<custom-domain>" Substitua <custom-domain> pelo domínio personalizado que você configurou na primeira etapa.
    "useHipCaptcha": true Altere o valor para true
    config.runtime.json "backendUrl": "https://<custom-domain>" Substitua <custom-domain> pelo domínio personalizado que você configurou na primeira etapa.
  4. Publique o portal.

  5. Carregue e hospede o portal recém-publicado recentemente.

  6. Expor o portal auto-hospedado por meio de um domínio personalizado.

O primeiro e segundo níveis do domínio do portal precisam corresponder ao domínio configurado na primeira etapa. Por exemplo, portal.contoso.com. As etapas exatas dependem da plataforma de hospedagem de sua escolha. Se você usou uma conta de armazenamento do Azure, pode consultar Mapear um domínio personalizado para um ponto de extremidade do Armazenamento de Blobs do Azure para obter instruções.

Próximas etapas