Como salvar e definir a configuração de seu serviço de Gerenciamento de API usando o Git

  • Artigo

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

Cada instância do serviço de Gerenciamento de API mantém um banco de dados de configuração que contém informações sobre a configuração e sobre os metadados da instância do serviço. É possível fazer alterações na instância de serviço alterando uma configuração no portal do Azure, usando ferramentas do Azure, como o Azure PowerShell ou a CLI do Azure, ou fazer uma chamada de API REST. Além desses métodos, você pode gerenciar a configuração da instância de serviço usando o Git, permitindo cenários como:

  • Controle de versão da configuração – baixe e armazene versões diferentes da configuração do seu serviço
  • Alterações de configuração em massa – faça alterações em várias partes da configuração de seu serviço no repositório local e integre essas alterações no servidor com uma única operação
  • Cadeia de ferramentas e fluxo de trabalho conhecido do Git – use as ferramentas e fluxo de trabalho do Git com os quais você já está familiarizado

O diagrama a seguir mostra uma visão geral das diferentes maneiras de configurar sua instância de serviço do Gerenciamento de API.

Diagrama que compara maneiras de configurar o Gerenciamento de API do Azure.

Quando você faz alterações em seu serviço usando o portal do Azure, ferramentas do Azure, como o Azure PowerShell ou a CLI do Azure, ou a API REST, você está gerenciando o banco de dados de configuração de seu serviço usando o ponto de extremidade https://{name}.management.azure-api.net, como exibido no lado direito do diagrama. O lado esquerdo do diagrama ilustra como você pode gerenciar a configuração de seu serviço usando o Git e o repositório Git de seu serviço localizado em https://{name}.scm.azure-api.net.

As etapas a seguir fornecem uma visão geral do gerenciamento de sua instância de serviço de Gerenciamento de API usando o Git.

  1. Acessar a configuração GIT em seu serviço
  2. Salvar o banco de dados de configuração de seu serviço em seu repositório Git
  3. Clonar o repositório Git em seu computador local
  4. Obter o repositório mais recente em seu computador local, confirmar e enviar as alterações de volta ao seu repositório
  5. Implantar as alterações de seu repositório para o banco de dados de configuração de seu serviço

Este artigo descreve como habilitar e usar o Git para gerenciar a configuração de seu serviço e fornece uma referência para os arquivos e pastas no repositório Git.

Importante

Essa funcionalidade foi projetada para trabalhar com configurações de serviço de Gerenciamento de API pequenas a médias, como as com tamanho exportado inferior a 10 MB ou com menos de 10.000 entidades. Serviços com um grande número de entidades (produtos, APIs, operações, esquemas etc.) podem apresentar falhas inesperadas ao processar comandos Git. Se você encontrar essas falhas, reduza o tamanho da configuração do serviço e tente novamente. Entre em contato com o Suporte do Azure se precisar de assistência.

Acessar a configuração GIT em seu serviço

  1. Navegue até sua instância de API Management no portal do Azure.

  2. No menu à esquerda, em Implantação e infraestrutura, selecione Repositório.

Captura de tela que mostra como acessar a configuração do Git para Gerenciamento de API.

Salvar a configuração do serviço no repositório Git

Cuidado

Os segredos que não foram definidos como valores nomeados são armazenados no repositório e permanecem no histórico. Os valores nomeados fornecem um local seguro para o gerenciamento de valores constantes de cadeia de caracteres, incluindo segredos, em todas as configurações e políticas de API. Portanto, não é necessário armazená-los nas próprias instruções de sua política. Para saber mais, confira Usar valores nomeados nas políticas de Gerenciamento de API do Azure.

Antes de clonar o repositório, salve o estado atual da configuração do serviço no repositório.

  1. Na página Repositório, selecione Salvar no repositório.

  2. Faça as alterações desejadas na tela de confirmação, como o nome do branch para salvar a configuração e selecione Salvar.

Após alguns instantes, a configuração será salva e o status da configuração do repositório será exibido, incluindo a data e a hora da última alteração de configuração e a última sincronização entre a configuração do serviço e o repositório.

Quando a configuração for salva no repositório, ele poderá ser clonado.

Para obter informações sobre como salvar a configuração de serviço usando a API REST, veja a Configuração do locatário – Salvar.

Obter credenciais de acesso

Para clonar um repositório, além da URL para seu repositório, você precisa de um nome de usuário e uma senha.

  1. Na página Repositório, selecione Credenciais de acesso na parte superior da página.

  2. Observe o nome de usuário fornecido na página Credenciais de acesso.

  3. Para gerar uma senha, primeiro verifique se a Validade está definida como a data e a hora de validade desejadas e selecione Gerar.

Importante

Anote essa senha. Depois que você sair desta página a senha não será exibida novamente.

Clone o repositório em seu computador local

Os exemplos a seguir usam a ferramenta Git Bash do Git para Windows, mas você pode usar qualquer ferramenta Git com a qual esteja familiarizado.

Abra sua ferramenta Git na pasta desejada e execute o comando a seguir para clonar o repositório Git em seu computador local usando o seguinte comando:

git clone https://{name}.scm.azure-api.net/

Quando solicitado, forneça o nome de usuário e a senha.

Se ocorrer algum erro, tente modificar seu comando git clone para incluir o nome de usuário e a senha, conforme exibido no exemplo a seguir.

git clone https://username:password@{name}.scm.azure-api.net/

Se isso resultar em erro, tente codificar na URL a parte da senha do comando. Uma maneira rápida de fazer isso é abrir o Visual Studio e emitir o seguinte comando na Janela Imediata. Para abrir a Janela Imediata, abra qualquer solução ou projeto no Visual Studio (ou crie um novo aplicativo de console vazio) e escolha Janelas, Imediata no menu Depuração.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

Use a senha codificada juntamente com seu nome de usuário e o local do repositório para construir o comando do git.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

Quando a clonagem terminar, altere o diretório para o repositório executando um comando como a seguir.

cd {name}.scm.azure-api.net/

Se você salvou a configuração em um branch diferente do branch padrão (master), confira o branch:

git checkout <branch_name>

Assim que o repositório for clonado, você poderá exibi-lo e trabalhar com ele no sistema de arquivos local. Para obter mais informações, veja Referência da estrutura de pastas e arquivos do repositório Git local.

Atualizar seu repositório local com a configuração mais recente da instância de serviço

Se você fizer alterações na instância de seu serviço de Gerenciamento de API no portal do Azure, ou usando as ferramentas do Azure, será necessário salvar essas alterações no repositório antes de poder atualizar seu repositório local com as alterações mais recentes.

Para salvar as alterações usando o portal do Azure, selecione Salvar no repositório na guia Repositório da sua instância de Gerenciamento de API.

Em seguida, para atualizar seu repositório local:

  1. Verifique se você está na pasta de seu repositório local. Se você acabou de concluir o comando git clone, será necessário alterar o diretório de seu repositório executando um comando parecido com o seguinte.

    cd {name}.scm.azure-api.net/

  2. Na pasta do repositório local, emita o comando a seguir.

    git pull

Enviar por push as alterações de seu repositório local para o repositório do servidor

Para enviar por push as alterações de seu repositório local para o repositório do servidor, você deve confirmar as alterações e, em seguida, enviá-las ao repositório do servidor. Para confirmar as alterações, abra sua ferramenta de comando do Git, alterne para o diretório de seu repositório local e execute os comandos a seguir.

git add --all
git commit -m "Description of your changes"

Para enviar por push todas as confirmações para o servidor, execute o comando a seguir.

git push

Implantar alterações da configuração do serviço na instância de serviço de Gerenciamento de API

Após a confirmação de suas alterações locais e o envio para o repositório do servidor, você pode implantá-las na instância de seu serviço de Gerenciamento de API.

  1. Navegue até sua instância de API Management no portal do Azure.

  2. No menu à esquerda, em Implantação e infraestrutura, selecione Repositório>Implantar no Gerenciamento de API.

  3. Na página Implantar configuração do repositório, insira o nome do branch que contém as alterações de configuração desejadas e, opcionalmente, selecione Remover assinaturas de produtos excluídos. Selecione Save.

Para obter informações sobre como executar essa operação usando a API REST, veja a Configuração do Locatário – Implantar.

Referência da estrutura de pastas e arquivos do repositório Git local

Os arquivos e pastas no repositório Git local contêm as informações de configuração sobre a instância do serviço.

Item Descrição
pasta api-management raiz Contém a configuração de nível superior da instância do serviço
apiReleases folder Contém a configuração das versões de API na instância de serviço
pasta apis Contém a configuração das APIs na instância de serviço
apiVersionSets folder Contém a configuração dos conjuntos de versão de API na instância de serviço
backends folder Contém a configuração das funcionalidades de back-end na instância de serviço
pasta groups Contém a configuração dos grupos na instância do serviço
pasta policies Contém as políticas na instância do serviço
pasta portalStyles Contém a configuração das personalizações do portal do desenvolvedor na instância do serviço
portalTemplates folder Contém a configuração dos modelos do portal do desenvolvedor na instância de serviço
pasta products Contém a configuração dos produtos na instância do serviço
pasta templates Contém a configuração dos modelos de email na instância do serviço

Cada pasta pode conter um ou mais arquivos e, em alguns casos, uma ou mais pastas, por exemplo, uma pasta para cada API, produto ou grupo. Os arquivos em cada pasta são específicos ao tipo de entidade descrito pelo nome da pasta.

Tipo de arquivo Finalidade
json Informações de configuração sobre a respectiva entidade
html Descrições sobre a entidade, geralmente exibidas no portal do desenvolvedor
Xml Declarações de políticas
css Folhas de estilo para personalização do portal do desenvolvedor

Esses arquivos podem ser criados, excluídos, editados e gerenciados em seu sistema de arquivos local, e as alterações podem ser implantadas de volta na instância de seu serviço de Gerenciamento de API.

Observação

As entidades a seguir não estão no repositório Git e não podem ser configuradas usando o Git.

  • Usuários
  • Assinaturas
  • Valores nomeados
  • Outras entidades do portal do desenvolvedor além dos estilos e modelos
  • Fragmentos de política

Pasta api-management raiz

A pasta api-management raiz contém um arquivo configuration.json com informações de alto nível sobre a instância do serviço no seguinte formato.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

As primeiras quatro configurações (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled e UserRegistrationTermsConsentRequired) são mapeadas para as seguintes configurações na guia Identidades da seção Portal do desenvolvedor.

Configuração de identidade É mapeada para
RegistrationEnabled Presença nome de usuário e senha provedor de identidade
UserRegistrationTerms Termos de uso na inscrição do usuário
UserRegistrationTermsEnabled Mostrar os termos de uso na página de entrada
UserRegistrationTermsConsentRequired Exigir consentimento
RequireUserSigninEnabled Redirecionar usuários anônimos para a página de entrada

As quatro configurações seguintes (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled e DelegationValidationKey) são mapeadas para as seguintes configurações na guia Delegação da seção Portal do desenvolvedor.

Configuração de delegação É mapeada para
DelegationEnabled Caixa de seleção Delegar entrada e inscrição
DelegationUrl URL do ponto de extremidade da delegação
DelegatedSubscriptionEnabled Delegar assinatura do produto
DelegationValidationKey Delegar Chave de Validação

A configuração final, $ref-policy, é mapeada para o arquivo de instruções de política global da instância do serviço.

apiReleases folder

A pasta apiReleases contém uma pasta para cada versão de API implantada em uma API de produção e contém os itens a seguir.

  • apiReleases\<api release Id>\configuration.json – configuração da versão, que contém informações sobre as datas de lançamento. Essas são as mesmas informações que retornariam se você chamasse a operação Obter uma versão específica.

pasta apis

A pasta apis contém uma pasta para cada API na instância do serviço que contém os itens a seguir.

  • apis\<api name>\configuration.json – configuração da API, contém informações sobre a URL do serviço de back-end e as operações. Essas são as mesmas informações que retornariam se você chamasse a operação Obter uma API específica.
  • apis\<api name>\api.description.html – descrição da API, correspondente à propriedade description da entidade de API na API REST.
  • apis\<api name>\operations\ – pasta que contém os arquivos <operation name>.description.html que são mapeados para as operações na API. Cada arquivo contém a descrição de uma única operação na API que mapeia para a propriedade description da entidade de operação na API REST.

apiVersionSets folder

A pasta apiVersionSets contém uma pasta para cada conjunto de versão de API criado para uma API e contém os itens a seguir.

  • apiVersionSets\<api version set Id>\configuration.json – configuração do conjunto de versão. Essas são as mesmas informações que retornariam se você chamasse a operação Obter um conjunto de versão específico.

pasta groups

A pasta groups contém uma pasta para cada grupo definido na instância do serviço.

  • groups\<group name>\configuration.json – configuração do grupo. Essas são as mesmas informações que retornariam se você chamasse a operação Obter um grupo específico .
  • groups\<group name>\description.html – descrição do grupo, corresponde à propriedade description da entidade de grupo.

pasta policies

A pasta policies contém as instruções da política para a instância de seu serviço.

  • policies\global.xml – políticas definidas no escopo global da instância de seu serviço.
  • policies\apis\<api name>\ – se houver políticas definidas no escopo da API, elas estarão nessa pasta.
  • Pasta policies\apis\<api name>\<operation name>\ – se houver políticas definidas no escopo da operação, elas estarão nessa pasta, nos arquivos <operation name>.xml, que são mapeados para as instruções da política de cada operação.
  • policies\products\ – se houver políticas definidas no escopo do produto, elas estarão nessa pasta, que contém os arquivos <product name>.xml, que são mapeados para as instruções da política de cada produto.

pasta portalStyles

A pasta portalStyles contém folhas de estilo e configuração para personalização do portal do desenvolvedor preterido da instância de serviço.

  • portalStyles\configuration.json – contém os nomes das folhas de estilo usadas pelo portal do desenvolvedor
  • portalStyles\<style name>.css – cada arquivo <style name>.css contém estilos para o portal do desenvolvedor (Preview.css e Production.css por padrão).

portalTemplates folder

A pasta portalTemplates contém modelos para personalizar o portal do desenvolvedor preterido da instância de serviço.

  • portalTemplates\<template name>\configuration.json – configuração do modelo.
  • portalTemplates\<template name>\<page name>.html – páginas HTML originais e modificadas do modelo.

pasta products

A pasta products contém uma pasta para cada produto definida na instância do serviço.

  • products\<product name>\configuration.json – configuração do produto. Essas são as mesmas informações que retornariam se você chamasse a operação Obter um produto específico .
  • products\<product name>\product.description.html – descrição do produto, correspondente à propriedade description da entidade do produto na API REST.

modelos

A pasta templates contém a configuração dos modelos de email na instância do serviço.

  • <template name>\configuration.json – configuração do modelo de email.
  • <template name>\body.html – corpo do modelo de email.

Próximas etapas

Para saber mais sobre outras maneiras de gerenciar sua instância de serviço, confira: