Como guardar e configurar a sua configuração do serviço de Gestão de API com Git

  • Artigo

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

Cada Gestão de API instância de serviço mantém uma base de dados de configuração que contém informações sobre a configuração e os metadados da instância de serviço. Pode efetuar alterações à instância de serviço ao alterar uma definição no portal do Azure, ao utilizar ferramentas do Azure, como Azure PowerShell ou a CLI do Azure, ou efetuar uma chamada à API REST. Além destes métodos, pode gerir a configuração da instância de serviço com o Git, ativando cenários como:

  • Controle de versão de configuração - Baixe e armazene diferentes versões 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 serviço no repositório local e integre as alterações de volta ao servidor com uma única operação
  • Cadeia de ferramentas e fluxo de trabalho Git familiares - Use as ferramentas e fluxos 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 de 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 seu banco de dados de configuração de serviço usando o https://{name}.management.azure-api.net ponto de extremidade, conforme mostrado no lado direito do diagrama. O lado esquerdo do diagrama ilustra como você pode gerenciar sua configuração de serviço usando o repositório Git e Git para 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. Aceda à configuração do Git no seu serviço
  2. Salve seu banco de dados de configuração de serviço em seu repositório Git
  3. Clone o repositório Git em sua máquina local
  4. Puxe o repositório mais recente para sua máquina local e confirme e envie as alterações de volta para o repositório
  5. Implantar as alterações do repositório no banco de dados de configuração de serviço

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

Importante

Esta funcionalidade foi concebida para funcionar com configurações pequenas e médias do serviço API Management, tais como as que têm um tamanho exportado inferior a 10 MB ou menos de 10.000 entidades. Os serviços com um grande número de entidades (produtos, APIs, operações, esquemas, etc.) podem sofrer falhas inesperadas ao processar comandos do Git. Se encontrar tais 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.

Aceda à configuração do Git no seu serviço

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

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

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

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

Atenção

Quaisquer segredos que não sejam definidos como valores nomeados serão armazenados no repositório e permanecerão em seu histórico. Os valores nomeados fornecem um local seguro para gerenciar valores de cadeia de caracteres constantes, incluindo segredos, em todas as configurações e políticas da API, para que você não precise armazená-los diretamente em suas declarações de política. Para obter mais informações, consulte Usar valores nomeados em 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 da ramificação para salvar a configuração, e selecione Salvar.

Após alguns momentos, a configuração é salva e o status da configuração do repositório é 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.

Uma vez que a configuração é salva no repositório, ela pode ser clonada.

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

Obter credenciais de acesso

Para clonar um repositório, além do URL para o 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 Expiração está definida para a data e hora de expiração desejadas e, em seguida, selecione Gerar.

Importante

Anote esta palavra-passe. Depois de sair desta página, a senha não será exibida novamente.

Clonar o repositório para o 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 a ferramenta Git na pasta desejada e execute o seguinte comando para clonar o repositório Git para sua máquina local, usando o seguinte comando:

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

Forneça o nome de usuário e a senha quando solicitado.

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

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

Se isso fornecer um erro, tente codificar URL a parte de 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 Windows, Immediate no menu Depurar .

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

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

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

Após a conclusão da clonagem, altere o diretório para o repositório executando um comando como o seguinte.

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

Se você salvou a configuração em uma ramificação diferente da ramificação padrão (master), confira a ramificação:

git checkout <branch_name>

Depois que o repositório for clonado, você poderá visualizá-lo e trabalhar com ele em seu sistema de arquivos local. Para obter mais informações, consulte Referência de estrutura de arquivos e pastas do repositório Git local.

Atualize seu repositório local com a configuração de instância de serviço mais atual

Se você fizer alterações em sua instância de serviço de Gerenciamento de API no portal do Azure ou usando outras ferramentas do Azure, deverá salvar essas alterações no repositório antes de 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 o repositório local:

  1. Verifique se você está na pasta do repositório local. Se você acabou de concluir o git clone comando, então você deve alterar o diretório para o seu repositório executando um comando como o seguinte.

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

  2. Na pasta do repositório local, execute o seguinte comando.

    git pull

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

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

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

Para enviar todas as confirmações para o servidor, execute o seguinte comando.

git push

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

Depois que as alterações locais forem confirmadas e enviadas por push para o repositório do servidor, você poderá implantá-las em sua instância de serviço de Gerenciamento de API.

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

  2. No menu à esquerda, em Implantação e infraestrutura, selecione Implantação de repositório>para gerenciamento de API.

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

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

Referência da estrutura de arquivos e pastas 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 de serviço.

Item Description
Pasta de gerenciamento de API raiz Contém configuração de nível superior para a instância de serviço
Pasta apiReleases Contém a configuração para as versões de API na instância de serviço
Pasta APIs Contém a configuração para as APIs na instância de serviço
Pasta apiVersionSets Contém a configuração para os conjuntos de versões da API na instância de serviço
Pasta de back-ends Contém a configuração para os recursos de back-end na instância de serviço
pasta de grupos Contém a configuração para os grupos na instância de serviço
Pasta Políticas Contém as políticas na instância de serviço
pasta portalStyles Contém a configuração para as personalizações do portal do desenvolvedor na instância de serviço
pasta portalTemplates Contém a configuração para os modelos do portal do desenvolvedor na instância de serviço
pasta de produtos Contém a configuração para os produtos na instância de serviço
pasta de modelos Contém a configuração para os modelos de email na instância de 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 dentro de cada pasta são específicos para o tipo de entidade descrito pelo nome da pasta.

Tipo de ficheiro Propósito
json Informações de configuração sobre a respetiva entidade
html Descrições sobre a entidade, geralmente exibidas no portal do desenvolvedor
xml Instruções de política
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 implantadas de volta à sua instância de serviço de Gerenciamento de API.

Nota

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

  • Utilizadores
  • Subscrições
  • Valores com nome
  • Entidades do portal do desenvolvedor diferentes de estilos e modelos
  • Fragmentos de política

Pasta de gerenciamento de api raiz

A pasta raiz api-management contém um configuration.json arquivo que contém informações de nível superior sobre a instância de 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 quatro primeiras configurações (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnablede UserRegistrationTermsConsentRequired) são mapeadas para as seguintes configurações na guia Identidades na seção Portal do desenvolvedor .

Configuração de identidade Mapas para
RegistrationEnabled Presença do provedor de identidade de nome de usuário e senha
UserRegistrationTermos Termos de uso na caixa de texto de inscrição do usuário
UserRegistrationTermsEnabled Mostrar a caixa de seleção Termos de uso na página de inscrição
UserRegistrationTermsConsentRequired Caixa de seleção Exigir consentimento
RequireUserSigninEnabled Caixa de verificação Redirecionar utilizadores anónimos para a página de início de sessão

As próximas quatro configurações (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnablede DelegationValidationKey) são mapeadas para as seguintes configurações na guia Delegação na seção Portal do desenvolvedor .

Configuração da delegação Mapas para
DelegaçãoHabilitada Caixa de verificação Delegar início de sessão & inscrição
DelegationUrl Caixa de texto URL do ponto de extremidade de delegação
DelegatedSubscriptionEnabled Caixa de verificação Delegar subscrição de produto
DelegationValidationKey Caixa de texto Delegar Chave de Validação

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

Pasta apiReleases

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

  • apiReleases\<api release Id>\configuration.json - Configuração para o lançamento, contendo informações sobre as datas de lançamento. Esta é a mesma informação que seria retornada se você chamasse a operação Obter uma liberação específica.

Pasta APIs

A apis pasta contém uma pasta para cada API na instância de serviço, que contém os seguintes itens.

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

Pasta apiVersionSets

A apiVersionSets pasta contém uma pasta para cada conjunto de versões da API criado para uma API e contém os seguintes itens.

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

pasta de grupos

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

  • groups\<group name>\configuration.json - Configuração para o grupo. Essas são as mesmas informações que seriam retornadas se você chamasse a operação Obter um grupo específico.
  • groups\<group name>\description.html- Descrição do grupo, correspondente à description propriedade da entidade do grupo.

Pasta Políticas

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

  • policies\global.xml - Políticas definidas no âmbito global para a sua instância de serviço.
  • policies\apis\<api name>\ - Se você tiver políticas definidas no escopo da API, elas estarão contidas nesta pasta.
  • policies\apis\<api name>\<operation name>\ folder - Se você tiver políticas definidas no escopo da operação, elas estarão contidas nessa pasta em <operation name>.xml arquivos mapeados para as instruções de política de cada operação.
  • policies\products\ - Se você tiver políticas definidas no escopo do produto, elas estarão contidas nesta pasta, que contém <product name>.xml arquivos mapeados para as declarações de política de cada produto.

pasta portalStyles

A portalStyles pasta contém folhas de configuração e estilo para personalizar o 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 <style name>.css arquivo contém estilos para o portal do desenvolvedor (Preview.cssProduction.css e por padrão).

pasta portalTemplates

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

  • portalTemplates\<template name>\configuration.json - Configuração do template.
  • portalTemplates\<template name>\<page name>.html - Páginas HTML originais e modificadas do modelo.

pasta de produtos

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

  • products\<product name>\configuration.json - Configuração para o produto. Esta é a mesma informação que seria retornada se você chamasse a operação Obter um produto específico.
  • products\<product name>\product.description.html- Descrição do produto, correspondente à description propriedade da entidade do produto na API REST.

modelos

A templates pasta contém a configuração para os modelos de email da instância de serviço.

  • <template name>\configuration.json - Configuração para o modelo de e-mail.
  • <template name>\body.html - Corpo do modelo de e-mail.

Próximos passos

Para obter informações sobre outras maneiras de gerenciar sua instância de serviço, consulte: