Auto-hospedar o portal do desenvolvedor do Gerenciamento de API

  • Artigo

APLICA-SE A: Developer | Básico | Padrão | Prémio

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.

Importante

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

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

Nota

O portal auto-hospedado não oferece suporte a controles de visibilidade e 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, mais adiante neste artigo.

Pré-requisitos

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

Etapa 1: configurar o ambiente local

Para configurar seu ambiente local, você terá que clonar o repositório, alternar para a versão mais recente do portal do desenvolvedor e instalar 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

Gorjeta

Use sempre a versão mais recente do portal e mantenha seu portal bifurcado atualizado. Os Engenheiros de Software usam a master ramificação deste repositório para fins de desenvolvimento diário. Tem versões instáveis do software.

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

O portal do desenvolvedor requer a API REST de gerenciamento de API para gerenciar o conteúdo.

config.design.json arquivo

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

{
  "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": "..."
      }
  }
}

Configure o arquivo:

  1. managementApiUrl No valor , substitua <service-name> pelo nome da sua instância 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 managementApiAccessToken valor.

  4. backendUrl No valor , substitua <service-name> pelo nome da sua instância 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, defina "useHipCaptcha": true. Certifique-se de definir as configurações do CORS para o back-end do portal do desenvolvedor.

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

    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 chave de API de credenciais>.
    4. Na caixa de diálogo aberta, copie a chave gerada e cole-a config.design.json como o valor de apiKey no arquivo.
    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",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Configure o arquivo:

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

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

config.runtime.json arquivo

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

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

Configure o arquivo:

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

  2. backendUrl No valor , substitua <service-name> pelo nome da sua instância 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"
...

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. Vá para sua 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 documento de índice, digite index.html.

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

  5. Selecione Guardar.

Definir configurações de CORS para conta de armazenamento

Configure as configurações de CORS (Cross-Origin Resource Sharing) para a conta de armazenamento:

  1. Vá para sua conta de armazenamento no portal do Azure e selecione CORS no menu à esquerda.

  2. Na guia Serviço de Blob, configure as seguintes regras:

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

  3. 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 nos backendUrl arquivos de configuração do portal) 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 usuário e assinatura de produto

Para adicionar configurações de CORS:

  1. Vá para sua instância de Gerenciamento de API no portal do Azure e selecione Configurações do Portal do Desenvolvedor>no menu à esquerda.
  2. 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://www.contoso.com
    • localhost para o desenvolvimento local (se aplicável), tais como http://localhost:8080 ou https://localhost:8080
  3. 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.

Execute o seguinte comando:

npm start

Após um curto período de 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. Qualquer alteração na base de código do projeto aciona 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 localmente

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

npm run publish

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 comando da CLI do Azure.

    Substitua <account-connection-string> pela cadeia de conexão da sua conta de armazenamento. Você pode obtê-lo na seção Chaves de acesso da sua conta de armazenamento.

    az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-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 (Ponto de extremidade primário em sites estáticos).

Etapa 8: 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 apontar 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:

Nota

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

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

Atualize o URL do portal do desenvolvedor no modelo de notificação de confirmação de alteração 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 manged, 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 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.

Gorjeta

Recomendamos o uso de uma conta de armazenamento separada config.publish.json no arquivo. Esta abordagem dá-lhe mais controlo e simplifica a gestão do serviço de alojamento do seu portal.

Próximos passos