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

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.

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.

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.

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

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.

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.

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.

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.

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 .

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 .

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 description propriedade 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.css Production.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:

• Referência ao cmdlet do Azure PowerShell
• Referência da CLI do Azure
• Referência da API REST de gerenciamento de API
• Versões do SDK do Azure