Auto-hospedagem do portal do desenvolvedor de Gerenciamento de API

APPLIES TO: Desenvolvedor | Básico | Básico v2 | Padrão | Standard v2 | Premium | Premium v2

Este tutorial descreve como hospedar por conta própria o portal de desenvolvedor do Gerenciamento de API. A auto-hospedagem é uma das várias opções para estender a funcionalidade do portal do desenvolvedor. Por exemplo, você pode hospedar automaticamente vários portais para sua instância de Gerenciamento de API, com recursos diferentes. Quando você auto-hospeda um portal, torna-se seu mantenedor e é responsável por suas atualizações. O portal do desenvolvedor requer a API REST de Gerenciamento de API para gerenciar o conteúdo.

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

Pré-requisitos

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

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

  Se você criou sua instância em um nível v2, habilite primeiro o portal do desenvolvedor.

  1. No menu da barra lateral, no portal do Desenvolvedor, selecione as configurações do Portal.
  2. Na janela de configurações do Portal, selecione Habilitado. Clique em Salvar. A habilitação do portal do desenvolvedor pode levar alguns minutos.

• Uma conta de armazenamento de blobs do Azure, que você usará para habilitar o recurso de sites estáticos. Consulte Criar uma conta de armazenamento.

• Git na sua máquina. Instale-o seguindo este tutorial do Git.

• Node.js (versão de Suporte de Longo Prazo (LTS), v10.15.0 ou posterior) e NPM no seu computador. Consulte Baixar e instalar Node.js e npm.

• CLI do Azure. Siga as etapas de instalação da CLI do Azure.

• Permissões para criar um registro de aplicativo do Microsoft Entra.

Etapa 1: Configurar o ambiente local

Para configurar seu ambiente local, clone o repositório, alterne para a versão mais recente do portal do desenvolvedor e instale pacotes npm.

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

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

2. Vá para a cópia local do repositório:

   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 marca de versão mais recente.

   git checkout <current-release-tag>
   

4. Instale todos os pacotes npm disponíveis:

   npm install
   

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

Arquivo config.design.json

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

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

Insira, em subscriptionId, resourceGroupName e serviceName, valores para a assinatura, o grupo de recursos e o nome do serviço da instância de Gerenciamento de API. I

Configurações opcionais no config.design.json

Opcionalmente, defina as seguintes configurações no config.design.json arquivo:

1. Se você quiser habilitar o CAPTCHA no portal do desenvolvedor, defina "useHipCaptcha": true. Defina as configurações do CORS para o back-end do portal do desenvolvedor.

   {
       ...
       "useHipCaptcha": true
       ...
   }
   

2. Em integration, em googleFonts, defina opcionalmente apiKey como uma chave de API do Google que permite acesso à API do Desenvolvedor de fontes da Web. Essa chave só será necessária se você quiser adicionar fontes do Google na seção Estilos do editor do portal do desenvolvedor.

   {
       ...
       "integration": {
           "googleFonts": {
               "apiKey": "< your Google API key >"
           }
       }
       ...
   }
   
   

3. Se você ainda não tiver uma chave, poderá 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 da Web está habilitada. Se não estiver, habilite-o.
   3. Selecione Criar credenciais>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. No menu suspenso, selecione API do Desenvolvedor de fontes da Web.
   7. Clique em Salvar.

Arquivo config.publish.json

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

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Copie e cole os valores de subscriptionId, resourceGroupName e serviceName do arquivo de configuração anterior.

Arquivo config.runtime.json

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

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

Substitua < service name > pelo nome da instância de Gerenciamento de API usada nos arquivos de configuração anteriores.

Configurar o site estático

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

1. No portal do Azure, acesse sua conta de armazenamento no portal do Azure.

2. No menu da barra lateral, selecione Gerenciamento de dados>Site estático.

3. Na página do site estático , selecione Habilitado.

4. No campo Nome do documento Índice , insiraindex.html.

5. No campo Caminho do documento erro , insira 404/index.html.

6. Clique em Salvar.

Anote a URL do ponto de extremidade primário . Você o configurará posteriormente para acessar seu portal auto-hospedado.

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

Para definir as configurações de CORS (compartilhamento de recursos entre origens) para a conta de armazenamento:

1. Acesse sua conta de armazenamento no portal do Azure.

2. No menu da barra lateral, em Configurações, selecione CORS (Compartilhamento de Recursos).

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

4. Clique em Salvar.

Definir configurações de CORS para back-end do portal do desenvolvedor

Defina as configurações do CORS para o back-end do portal do desenvolvedor para permitir solicitações originadas por meio do portal do desenvolvedor auto-hospedado. O portal do desenvolvedor auto-hospedado depende do ponto de extremidade de backend do portal do desenvolvedor (definido em backendUrl no arquivo config.runtime.json do portal) para habilitar vários recursos, incluindo:

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

Para adicionar configurações de CORS:

1. Acesse sua instância de Gerenciamento de API no portal do Azure.
2. No menu da barra lateral, selecioneConfigurações do portal >do Desenvolvedor.
3. Na guia configuração do portal auto-hospedado , adicione um ou mais valores de domínio origin . Por exemplo:
   • O domínio em que o portal auto-hospedado está hospedado, como https://contoso.developer.azure-api.net
   • localhost para desenvolvimento local (se aplicável), como http://localhost:8080 ou https://localhost:8080
4. Clique em 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.

1. Execute o comando a seguir:

   npm run start
   

2. Você será solicitado a autenticar por meio do navegador. Selecione suas credenciais da Microsoft para continuar.

3. Após algum tempo, o navegador padrão é aberto automaticamente com a instância do portal do desenvolvedor local. O endereço padrão é http://localhost:8080, mas a porta pode ser alterada se 8080 já estiver ocupada. Quando você faz alterações na base de código do projeto, ele dispara uma recompilação e atualiza a janela do navegador.

Etapa 4: Editar por meio do editor visual

Use o editor visual para realizar estas tarefas:

• Personalizar o portal
• Conteúdo do autor
• Organizar a estrutura do site
• Estilize sua aparência

Confira o 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 para o conteúdo padrão. Salve todas as alterações no ambiente local e pressione Ctrl+C para fechá-la.

Etapa 5: publicar o portal localmente

1. Execute npm run publish. Você será solicitado a autenticar por meio do navegador. Selecione suas credenciais da Microsoft para continuar.

2. Após algum tempo, o conteúdo é publicado na dist/website pasta.

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 a seguir az storage blog upload-batch . Substitua <connection-string> por uma cadeia de conexão para sua conta de armazenamento. Você pode obtê-lo na seção segurança + rede> chaves deacesso da sua conta de armazenamento.

   az storage blob upload-batch --source dist/website \
       --account-name <your-storage-account-name> \
       --destination '$web' \
       --connection-string "<connection-string>"
   

Etapa 7: Vá para seu site

Seu site agora está ativo no hostname especificado nas propriedades do seu Armazenamento do Azure. No menu da barra lateral, acesse Gerenciamento de dados>Site estático. O nome do host é o valor do ponto de extremidade primário.

Hospedar o editor do site

Ao fazer alterações no código do site, talvez seja necessário atualizar o código do editor do site para poder dar suporte adequado à edição de seus widgets modificados. Nesse caso, além de hospedar o portal, talvez você também queira hospedar o aplicativo editor. Para isso, você precisa compilá-lo e configurá-lo para acessar o serviço de Gerenciamento de API.

Para isso, você precisa de um aplicativo de ID do Microsoft Entra em seu locatário:

1. Registrar um aplicativo no seu locatário do Microsoft Entra ID. Anote o ID do aplicativo (cliente) e o ID do diretório (inquilino). Configure-os em uma etapa posterior.
2. Configure um URI de Redirecionamento da Web (URL de resposta) nesta aplicação para direcionar ao endpoint do aplicativo Web onde o designer está hospedado. Normalmente, esse é o local do site baseado em armazenamento de blobs. Exemplo: https://<your-storage-account-name>z13.web.core.windows.net/.
3. Se você quiser publicar o portal em pipelines (ex.: ações do GitHub), crie também um segredo de cliente para este aplicativo. Anote o valor do segredo gerado e armazene-o em um local seguro.

Em seguida, siga estas etapas para hospedar o editor do site:

1. Adicione clientId e tenantId campos ao config.design.json arquivo.

   {
       ...
       "clientId": "< Entra ID app ID >",
       "tenantId": "< Entra ID tenant ID >"
       ...
   }
   

2. Execute o npm run build-designer comando para criar o designer.

3. Vá para a pasta gerada /dist/designer , que contém um arquivo config.json com o seguinte conteúdo:

   {
       "subscriptionId": "< subscription ID >",
       "resourceGroupName": "< resource group name >",
       "serviceName": "< API Management service name >",
       "clientId": "< Entra ID client ID >",
       "tenantId": "< Entra ID tenant ID >"
   }
   

4. Confirme a configuração de subscriptionId, resourceGroupName e serviceName, que são necessários para se conectar ao seu serviço de Gerenciamento de API usando APIs do Azure Resource Manager.

Publicar portal em pipelines (GitHub Actions)

Você pode publicar o portal auto-hospedado em um pipeline, como o GitHub Actions.

O pipeline também precisa das credenciais do aplicativo Entra ID para executar a publicação usando pipelines. Você pode usar o mesmo aplicativo de ID do Entra descrito nas etapas anteriores. O tenantId, clientId e especialmente clientSecret devem ser mantidos no respectivo armazenamento de chaves. Consulte Como usar segredos no GitHub Actions para obter mais detalhes.

Exemplo do pipeline YAML do GitHub Actions:

name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

Alterar modelos de notificação do Gerenciamento de API

Substitua a URL do portal do desenvolvedor nos modelos de notificação do Gerenciamento de API para que ele aponte para o portal auto-hospedado. Veja como configurar notificações e modelos de email no Gerenciamento de API do Azure.

Em particular, execute as seguintes alterações nos modelos padrão:

Confirmação de alteração de email

Atualize a URL do portal do desenvolvedor no modelo de notificação de confirmação de mudança de e-mail.

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 nova conta 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 convite de 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

Atualizar 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>

Migrar de um portal de desenvolvedor gerenciado para um portal de desenvolvedor auto-hospedado

Com o tempo, seus requisitos de negócios podem mudar. Você pode acabar em uma situação em que a versão gerenciada do portal do desenvolvedor do Gerenciamento de API não atende mais às suas necessidades. Por exemplo, um novo requisito pode forçar você a criar um widget personalizado que se integra a um provedor de dados de terceiros. Ao contrário da versão gerenciada, a versão auto-hospedada 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 auto-hospedada na mesma instância do serviço de Gerenciamento de API. O processo preserva as modificações realizadas na versão gerenciada do portal. Faça backup do conteúdo do portal com antecedência. Você pode encontrar o script de backup na scripts.v3 pasta 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 auto-hospedado genérico, conforme mostrado nas etapas anteriores neste artigo. Há uma exceção na etapa de configuração. A conta de armazenamento no config.design.json arquivo precisa ser a mesma da conta de armazenamento da versão gerenciada do portal. Confira o Tutorial: Use uma identidade atribuída pelo sistema de VM linux para acessar o Armazenamento do Azure por meio de uma credencial SAS para obter instruções sobre como recuperar a URL sas.

Conteúdo relacionado

• Saiba mais sobre abordagens alternativas para auto-hospedagem