Implantar proxies de API usando a API

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Toda organização tem um ciclo de vida de desenvolvimento de software (SDLC, na sigla em inglês) exclusivo. Muitas vezes, é necessário sincronizar e alinhar a implantação do proxy de API com os processos usados para serviços de back-end.

Os métodos da API Edge demonstrados neste tópico podem ser usados para integrar o gerenciamento de proxy de API ao SDLC da sua organização. Um uso comum dessa API é escrever scripts ou códigos que implantam proxies de API ou que migram proxies de API de um ambiente para outro, como parte de um processo automatizado maior que também implanta ou migra outros aplicativos.

A API Edge não faz suposições sobre seu SDLC (ou de qualquer outra pessoa). Em vez disso, ele expõe funções atômicas que podem ser coordenadas pela equipe de desenvolvimento para automatizar e otimizar o ciclo de vida de desenvolvimento da API.

Para informações completas, consulte APIs Edge.

Para usar a API Edge, você precisa se autenticar nas chamadas. É possível fazer isso com um dos seguintes métodos:

Este tópico se concentra no conjunto de APIs para gerenciar proxies de API.

Vídeo:assista este vídeo curto para saber como implantar uma API.

Como interagir com a API

As etapas a seguir orientam você nas interações simples com as APIs.

Listar APIs na sua organização

Comece listando todos os proxies de API na sua organização. (Lembre-se de substituir as entradas por EMAIL:PASSWORD e ORG_NAME. Para instruções, consulte Usar a API Edge.

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Exemplo de resposta:

[ "weatherapi" ]

Acessar uma API

É possível chamar o método GET em qualquer proxy de API na sua organização. Essa chamada retorna uma lista de todas as revisões disponíveis do proxy de API.

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Exemplo de resposta:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

O único detalhe retornado por esse método é o nome do proxy de API com a revisão associada, que tem um número associado. Os proxies de API consistem em um pacote de arquivos de configuração As revisões fornecem um mecanismo leve para gerenciar as atualizações da configuração conforme você as itera. As revisões são numeradas sequencialmente, permitindo que você reverta uma alteração implantando uma revisão anterior do proxy de API. Além disso, é possível implantar uma revisão de um proxy de API no ambiente de produção, enquanto você continua criando novas revisões desse proxy de API no ambiente de teste. Quando estiver pronto, é possível promover a revisão mais alta do proxy de API no ambiente de teste com a revisão anterior do proxy de API no ambiente de produção.

Neste exemplo, há apenas uma revisão porque o proxy de API acabou de ser criado. À medida que um proxy de API passa pelo ciclo de vida da configuração e implantação iterativa, o número da revisão aumenta em números inteiros. Usando chamadas diretas de API para implantar, é possível aumentar o número da revisão do proxy de API. Às vezes, quando você faz pequenas alterações, talvez não queira aumentar a revisão.

Acessar a revisão da API

A versão da API (por exemplo, api.company.com/v1) deve mudar com pouca frequência. Quando você aumenta a versão da API, isso significa para os desenvolvedores que houve uma mudança significativa na assinatura da interface externa exposta pela API.

A revisão do proxy de API é um número incrementado associado a uma configuração de proxy de API. Os serviços de API mantêm revisões das suas configurações para que você possa reverter uma configuração quando algo der errado. Por padrão, a revisão de um proxy de API é automaticamente incrementada sempre que você importa um proxy de API usando a API Importar um proxy de API. Se você não quiser aumentar a revisão de um proxy de API, use a Atualizar a revisão de proxy de API API. Se você estiver usando o Maven para implantar, use as clean ou update opções, conforme descrito no arquivo Leia-me do plug-in Maven.

Por exemplo, é possível chamar o método GET na revisão 1 do proxy de API para ter uma visualização detalhada.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Exemplo de resposta

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Esses elementos de configuração de proxy de API são documentados em detalhes na referência de configuração de proxy de API.

Como implantar uma API em um ambiente

Depois que o proxy de API for configurado para receber e encaminhar solicitações corretamente, você poderá implantá-lo em um ou mais ambientes. Normalmente, você itera proxies de API em test e, quando estiver pronto, você promove a revisão do proxy de API para prod. Muitas vezes, você terá muito mais revisões de um proxy de API no ambiente de teste, principalmente porque fará muito menos iterações no ambiente de produção.

Um proxy de API não pode ser invocado até ser implantado em um ambiente. Depois de implantar a revisão do proxy de API na produção, você poderá publicar o prod URL para desenvolvedores externos.

Como listar ambientes

Toda organização no Apigee Edge tem pelo menos dois ambientes: test e prod. A distinção é arbitrária. O objetivo é fornecer uma área para verificar se o proxy de API está funcionando corretamente antes de abri-lo para desenvolvedores externos.

Cada ambiente é apenas um endereço de rede, permitindo separar o tráfego entre os proxies de API em que você está trabalhando e aqueles que são acessados por aplicativos no tempo de execução.

Ambientes também fornecem segregação de dados e recursos. Por exemplo, é possível configurar caches diferentes em teste e produção, que podem ser acessados apenas por proxies de API em execução nesse ambiente.

Conferir ambientes em uma organização

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Exemplo de resposta

[ "test", "prod" ]

Explorar as implantações

Uma implantação é uma revisão de um proxy de API que foi implantado em um ambiente. Um proxy de API no estado implantado pode ser acessado pela rede, nos endereços definidos no elemento <VirtualHost> para esse ambiente.

Como implantar proxies de API

Os proxies de API não podem ser invocados até serem implantados. Os serviços de API expõem APIs RESTful que fornecem controle sobre o processo de implantação.

Apenas uma revisão de um proxy de API pode ser implantada em um ambiente por vez. Portanto a revisão implantada precisa ser removida. É possível controlar se o novo pacote é implantado como uma nova revisão ou se ele substitui a revisão atual.

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Primeiro, cancele a implantação da revisão atual. Especifique o nome do ambiente e o número da revisão de o proxy de API que você quer remover:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Em seguida, implante a nova revisão. A nova revisão do proxy de API já precisa existir: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Implantação contínua (tempo de inatividade zero)

Para minimizar a possibilidade de inatividade durante a implantação, use o parâmetro override no método de implantação e defina-o como true.

Não é possível implantar uma revisão de um proxy de API em cima de outra. A primeira sempre precisa ser removida. Ao definir override como true, você indica que uma revisão de um proxy de API precisa ser implantada na revisão implantada no momento. O resultado é que a sequência de implantação é invertida: a nova revisão é implantada e, quando a implantação é concluída, a revisão já implantada é removida.

O exemplo a seguir define o valor override transmitindo-o como um parâmetro de formulário: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

É possível otimizar ainda mais a implantação definindo o parâmetro delay. O delay parâmetro especifica um intervalo de tempo, em segundos, antes do qual a revisão anterior precisa ser removida. O efeito é que as transações em andamento têm um intervalo de tempo em que podem ser concluídas antes que o proxy de API que processa a transação seja removido. A seguir, o que ocorre com override=true e o parâmetro delay definido:

  • A revisão 1 está processando solicitações.
  • A revisão 2 está sendo implantada em paralelo.
  • Quando a revisão 2 estiver totalmente implantada, o novo tráfego será enviado para a revisão 2. Nenhum novo tráfego é enviado para a revisão 1.
  • No entanto, a revisão 1 ainda pode estar processando transações atuais. Ao definir o delay parâmetro (por exemplo, 15 segundos), você dá à revisão 1 15 segundos para terminar de processar as transações atuais.
  • Após o intervalo de atraso, a revisão 1 é removida.
curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD
Parâmetro de consulta Descrição
override

O padrão é false (comportamento normal de implantação: a revisão atual é removida e, em seguida, a nova revisão é implantada).

Defina como true para substituir o comportamento normal de implantação e fornecer uma implantação contínua. A revisão atual permanece implantada enquanto a nova revisão também está sendo implantada. Quando a nova revisão é implantada, a antiga é removida. Use em conjunto com o parâmetro delay para controlar quando a remoção ocorre.
delay

Para permitir que o processamento de transações seja concluído na revisão atual antes de ser removido e eliminar a possibilidade de 502 Bad Gateway ou 504 Gateway Timeout errors—defina esse parâmetro como o número de segundos que você quer que a remoção seja atrasada. Não há limite para o número de segundos que você pode definir, e não há ramificações de desempenho para definir um grande número de segundos. Durante o atraso, nenhum novo tráfego é enviado para a revisão antiga.

O padrão é 0 (zero) segundos. Quando override é definido como verdadeiro e delay é 0, a revisão atual é removida imediatamente após a implantação da nova revisão. Valores negativos são tratados como 0 (zero) segundos.

Quando override=true é usado com um delay, as respostas HTTP 5XX durante a implantação podem ser eliminadas. Isso ocorre porque as duas revisões de proxy de API serão implantadas simultaneamente, com a revisão mais antiga removida após o atraso.

Conferir todas as implantações de uma revisão de API

Às vezes, é necessário buscar uma lista de todas as revisões implantadas de um proxy de API.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD
 
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

A resposta acima contém muitas propriedades específicas da infraestrutura interna do Apigee Edge. A menos que você esteja usando o Apigee Edge on-premise, não é possível mudar essas configurações.

As propriedades importantes contidas na resposta são organization, environment, aPIProxy, name e state. Ao analisar esses valores de propriedade, é possível confirmar que uma revisão específica de um proxy de API está implantada em um ambiente.

Conferir todas as implantações no ambiente de teste

Também é possível recuperar o status de implantação de um ambiente específico (incluindo o número da revisão do proxy de API implantado no momento) usando a seguinte chamada:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Isso retorna o mesmo resultado acima para cada API implantada no ambiente de teste.

Conferir todas as implantações na sua organização

Para buscar uma lista de todas as revisões implantadas de todos os proxies de API em todos os ambientes, use o seguinte método de API:

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

Isso retorna o mesmo resultado acima para todos os proxies de API implantados em todos os ambientes.

Como a API é RESTful, é possível usar o método POST, junto com um payload JSON ou XML, no mesmo recurso para criar um proxy de API.

Um perfil para o proxy de API é gerado. A representação padrão de um proxy de API está em notação de objeto JavaScript (JSON). Confira abaixo a resposta JSON padrão à solicitação POST acima, que criou um proxy de API chamado weatherapi. A seguir, uma descrição de cada elemento no perfil segue:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

O perfil de proxy de API gerado demonstra a estrutura completa de um proxy de API:

  • APIProxy revision: a iteração numerada sequencialmente da configuração do proxy de API, conforme mantida pelos serviços de API
  • APIProxy name: o nome exclusivo do proxy de API
  • ConfigurationVersion: versão dos serviços de API a que a configuração do proxy de API está em conformidade
  • CreatedAt: hora em que o proxy de API foi gerado, formatado no horário do UNIX
  • CreatedBy: endereço de e-mail do usuário do Apigee Edge que criou o proxy de API
  • DisplayName: um nome amigável para o proxy de API
  • LastModifiedAt: hora em que o proxy de API foi gerado, formatado no horário do UNIX
  • LastModifiedBy: endereço de e-mail do usuário do Apigee Edge que criou o proxy de API
  • Policies: uma lista de políticas que foram adicionadas a esse proxy de API
  • ProxyEndpoints: uma lista de ProxyEndpoints nomeados
  • Resources: uma lista de recursos (JavaScript, Python, Java, XSLT) disponíveis para execução nesse proxy de API
  • TargetServers: uma lista de TargetServers nomeados (que podem ser criados usando a API Management), usados em configurações avançadas para fins de balanceamento de carga
  • TargetEndpoints: uma lista de TargetEndpoints nomeados

Muitos dos elementos da configuração de proxy de API criados usando o método POST simples acima estão vazios. Nos tópicos a seguir, você vai aprender a adicionar e configurar os principais componentes de um proxy de API.

Também é possível ler sobre esses elementos de configuração na referência de configuração de proxy de API.

Como criar scripts na API

O artigo Como usar os proxies de API de amostra, disponível no GitHub, fornece scripts de shell que envolvem a ferramenta de implantação da Apigee. Se, por algum motivo não for possível usar a ferramenta de implantação do Python, chame a API diretamente. As duas abordagens são demonstradas nos scripts de amostra abaixo.

Como envolver a ferramenta de implantação

Primeiro, verifique se a ferramenta de implantação do Python está disponível no seu ambiente local.

Em seguida, crie um arquivo para armazenar suas credenciais. Os scripts de implantação que você escrever vão importar essas configurações, ajudando a gerenciar centralmente as credenciais da sua conta. No exemplo da plataforma de API, esse arquivo é chamado de setenv.sh.

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

O arquivo acima disponibiliza todas as suas configurações para os scripts de shell que envolvem a ferramenta de implantação.

Agora, crie um script de shell que importe essas configurações e as use para chamar a ferramenta de implantação. Para um exemplo, consulte Exemplos da plataforma de API da Apigee.

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

Para facilitar sua vida, crie também um script para invocar e testar a API, da seguinte maneira:

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

Como invocar a API diretamente

Pode ser útil escrever scripts de shell simples que automatizam o processo de upload e implantação de proxies de API.

O script abaixo invoca diretamente a API Management. Ele remove a revisão atual de o proxy de API que você está atualizando, cria um arquivo ZIP no diretório /apiproxy que contém os arquivos de configuração do proxy e, em seguida, faz upload, importa e implanta a configuração.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST