Hospedar por conta própria o portal do desenvolvedor da Gestão de API

APLICA-SE A: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Este tutorial descreve como hospedar automaticamente o portal do desenvolvedor do Gerenciamento de API. A hospedagem automática é uma das várias opções para estender a funcionalidade do portal do desenvolvedor. Por exemplo, você pode autohospedar vários portais para sua instância de Gerenciamento de API, com recursos diferentes. Quando você hospeda um portal automaticamente, você se torna 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 de serviço de Gerenciamento de API. Se você não tiver uma, consulte Guia de início rápido - Criar uma instância de Gerenciamento de API do Azure.

  Se você criou sua instância em uma camada de serviço v2, primeiro habilite o portal do desenvolvedor.

  1. No menu da barra lateral, em Portal do desenvolvedor, selecione Configurações do portal.
  2. Na janela Configurações do portal, selecione Habilitado. Selecione Guardar. Pode levar alguns minutos para habilitar o portal do desenvolvedor.

• Para habilitar o recurso de sites estáticos, uma conta de armazenamento de blob do Azure será utilizada. Consulte Criar uma conta de armazenamento.

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

• Node.js (versão v10.15.0 LTS (Long Term Support) ou posterior) e npm na sua máquina. Consulte Download e instalação do 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 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 sua cópia local do repositório:

   cd api-management-developer-portal
   

3. Confira a última versão do portal.

   Antes de executar o código a seguir, verifique a tag de versão atual na seção Releases do repositório e substitua <current-release-tag> o valor pela tag de release mais recente.

   git checkout <current-release-tag>
   

4. Instale todos os pacotes npm disponíveis:

   npm install
   

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

config.design.json arquivo

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 >"
}

Em subscriptionId, resourceGroupNamee serviceName, insira valores para a assinatura, o grupo de recursos e o nome do serviço da sua 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. Certifique-se de definir 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 o acesso à API do desenvolvedor de fontes da Web. Essa chave só é 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 ainda não tiver uma chave, pode configurá-la utilizando a consola do Google Cloud. Siga estes passos:

   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 ficheiro config.design.json.
   5. Selecione Editar chave da API para abrir o editor de chaves.
   6. No editor, em Restrições da API, selecione Restringir chave. Na lista suspensa, selecione Web Fonts Developer API.
   7. Selecione Guardar.

config.publish.json arquivo

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 subscriptionIdvalores , resourceGroupNamee serviceName do arquivo de configuração anterior.

config.runtime.json arquivo

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 o índice e as páginas de erro:

1. No portal do Azure, vá para sua conta de armazenamento no portal do Azure.

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

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

4. No campo Nome do documento de índice , digite index.html.

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

6. Selecione Guardar.

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

Definir configurações de CORS para conta de armazenamento

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

1. Aceda à sua conta de armazenamento no Portal do Azure.

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

3. Na guia Serviço de 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. Selecione Guardar.

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

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

• Verificação CAPTCHA
• Autorização do OAuth 2.0 no console de teste
• Delegação de autenticação de utilizador e subscrição de produto

Para adicionar configurações de CORS:

1. Vá para 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 onde o portal auto-hospedado está hospedado, como https://contoso.developer.azure-api.net
   • localhost para o desenvolvimento local (se aplicável), tais como http://localhost:8080 ou https://localhost:8080
4. Selecione Guardar.

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 seguinte comando:

   npm run start
   

2. Ser-lhe-á pedido para se autenticar através do seu browser. Selecione suas credenciais da Microsoft para continuar.

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

Passo 4: Editar através do editor visual

Use o editor visual para realizar estas tarefas:

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

Consulte Tutorial: Acessar e personalizar o portal do desenvolvedor. Ele abrange os conceitos básicos da interface administrativa do usuário 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á-lo.

Etapa 5: Publicar o portal localmente

1. Execute npm run publish. Ser-lhe-á pedido para se autenticar através do seu browser. 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 para um blob

Use a CLI do Azure para carregar os arquivos estáticos gerados localmente em um blob e certifique-se de que seus visitantes possam acessá-los:

1. Abra o Prompt de Comando do Windows, o PowerShell ou outro shell de comando.

2. Execute o seguinte az storage blog upload-batch comando. Substitua <connection-string> por uma cadeia de conexão para sua conta de armazenamento. Pode obtê-lo a partir da secção Segurança + chavesde> à rede 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>"
   

Passo 7: Aceda ao seu website

Seu site agora está ativo sob o nome de host especificado em suas propriedades de Armazenamento do Azure. No menu da barra lateral, vá para Gerenciamento de dados>Site estático. O hostname é o valor do endpoint primário.

Hospede o editor do site

Ao fazer alterações no código do site, você pode precisar atualizar o código do editor do site, bem como para ser capaz de suportar adequadamente a edição de seus widgets modificados. Neste caso, além de hospedar o portal, você também pode querer hospedar o aplicativo editor. Para isso, você precisa criá-lo e configurá-lo para acessar seu serviço de Gerenciamento de API.

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

1. Registre um aplicativo em seu locatário do Microsoft Entra ID. Anote a ID do aplicativo (cliente) e a ID do diretório (tenant). Você os configura em uma etapa posterior.
2. Configure uma URI de Redirecionamento da Web (URL de resposta) nesta aplicação para apontar para o endpoint da aplicação 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 quiser publicar o portal em pipelines (Ações do GitHub), crie também um segredo de cliente para esta aplicação. Anote o valor secreto gerado e armazene-o em um local seguro.

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

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

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

2. Execute o comando npm run build-designer para compilar 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árias para se conectar ao seu serviço de Gestão 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 de credenciais do aplicativo Entra ID para executar a publicação usando pipelines. Você pode usar o mesmo aplicativo Entra ID descrito nas etapas anteriores. O tenantId, clientId e especialmente clientSecret devem ser mantidos no respetivo armazenamento de chaves. Consulte Usando segredos nas ações do GitHub para obter mais detalhes.

Exemplo de pipeline de ações do GitHub YAML:

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 ela aponte para seu portal auto-hospedado. Consulte Como configurar notificações e modelos de email no Gerenciamento de API do Azure.

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

Confirmação de alteração de e-mail

Atualize o 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>

Atualizado

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

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

Conteúdo original

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

Atualizado

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

Convidar utilizador

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

Conteúdo original

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

Atualizado

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

Nova subscrição ativada

Atualize o URL do portal do desenvolvedor no modelo de notificação 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!

Atualizado

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

Atualizado

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>

Atualizado

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

Atualizado

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

Confirmação de alteração de palavra-passe

Atualize o 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>

Atualizado

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

Atualizado

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

Mudar do portal do desenvolvedor gerenciado para o auto-hospedado

Com o tempo, os requisitos do seu negócio 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çá-lo a criar um widget personalizado que se integre a um provedor de dados de terceiros. Ao contrário da versão gerenciada, a versão auto-hospedada do portal oferece total flexibilidade e extensibilidade.

Processo de transição

Você pode fazer a transição da versão gerenciada para uma versão auto-hospedada dentro da mesma instância de 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 scripts.v3 script de backup na 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, como 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 que a conta de armazenamento da versão gerenciada do portal. Consulte Tutorial: Usar 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