Implantar proxies de API usando a API

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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

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

A API Edge não faz suposições sobre seu SDLC (ou 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 de APIs.

Para conferir as informações completas, consulte as APIs do Edge.

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

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

Vídeo:confira este vídeo curto para aprender a implantar uma API.

Interagir com a API

As etapas a seguir mostram 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 entradas para EMAIL:PASSWORD e ORG_NAME. Para instruções, consulte Use a API Edge.

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

Exemplo de resposta:

[ "weatherapi" ]

Acessar uma API

Você pode 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 junto com o nome revision, que tem um número associado. Os proxies das APIs consistem em um pacote de arquivos de . As revisões fornecem um mecanismo leve para gerenciar as atualizações da configuração. à medida que você itera. As revisões são numeradas sequencialmente, o que permite reverter uma alteração com a implantação uma revisão anterior do seu proxy de API. Além disso, é possível implantar uma revisão de um proxy de API no ambiente de produção, enquanto continua a criar novas revisões desse proxy de API no ambiente de nuvem. Quando estiver tudo pronto, promova a revisão superior do proxy de API na ambiente de teste em relação à 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. Como uma API proxy se move ao longo do ciclo de vida da configuração e implantação iterativas, o número de revisão incrementos por números inteiros. Usando chamadas de API diretas para implantar, é possível, opcionalmente, incrementar o número de revisão do proxy de API. Às vezes, quando você faz pequenas alterações, pode não querer incrementar a revisão.

Acessar revisão da API

A versão da API (por exemplo, api.company.com/v1) mudará muito. com pouca frequência. Ao incrementar a versão da API, isso significa para os desenvolvedores que há 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 um proxy de API. configuração do Terraform. Os Serviços de API mantêm revisões das suas configurações para que você possa reverter uma configuração quando algo dá errado. Por padrão, a revisão de um proxy de API é criada é incrementado toda vez que você importa um proxy de API usando a API Import an API proxy. Se você não quiser incrementar a revisão de um proxy de API, use o comando API de revisão do proxy de API. Se você estiver usando o Maven para implantar, utilize o clean ou update, conforme descrito no plug-in do Maven leia-me.

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 estão documentados em detalhes na referência de configuração de proxy de API.

Implantar uma API em um meio ambiente

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

Não é possível invocar um proxy de API até que ele seja implantado em um ambiente. Depois de ter implantou a revisão do proxy de API na produção, é possível publicar o URL prod no desenvolvedores de aplicativos.

Como listar ambientes

Toda organização no Apigee Edge tem pelo menos dois ambientes: test e prod. A a distinção é arbitrária. O objetivo é oferecer uma área para verificar se o proxy de API funciona corretamente antes de ser disponibilizado para desenvolvedores externos.

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

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

Visualize ambientes em uma organização

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

Exemplo de resposta

[ "test", "prod" ]

Explore as implantações

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

Como implantar proxies de API

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

Somente uma revisão de um proxy de API pode ser implantada em um ambiente por vez. Então a revisão implantada precisa ser cancelada. É possível controlar se o novo pacote será implantado como uma nova revisão ou se ela substitui a revisão existente.

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Primeiro, cancele a implantação da revisão atual. Especifique o nome do ambiente e o número da revisão do 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 simples (sem inatividade)

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

Não é possível implantar uma revisão de um proxy de API sobre outra. A primeira deve sempre ser não implantado. Ao definir override como true, você indica que uma revisão de um proxy de API devem ser implantados durante a revisão implantada atualmente. O resultado é que a sequência de implantação é revertida. A nova revisão é implantada e, quando ela é concluída, a implantação da revisão já foi cancelada.

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. A O parâmetro delay especifica um intervalo de tempo, em segundos, antes do qual o parâmetro a implantação será desimplantada. Por isso, as transações em andamento têm um intervalo de tempo que deve ser concluída antes da remoção da implantação do proxy de API que processa a transação. Seguir é o que ocorre com override=true e o conjunto de parâmetros delay:

  • A Revisão 1 está cuidando das solicitações.
  • A Revisão 2 está sendo implantada em paralelo.
  • Quando a revisão 2 for totalmente implantada, o novo tráfego será enviado para ela. Nenhum tráfego novo é enviados para a Revisão 1.
  • No entanto, é possível que a Revisão 1 ainda esteja processando as transações atuais. Ao definir o delay (por exemplo, 15 segundos), você concede 15 segundos para a Revisão 1 concluir o processamento das transações atuais.
  • Após o intervalo de atraso, a revisão 1 é desimplantada.
. 
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 de implantação normal: a revisão atual não é implantada, uma nova revisão é implantada).

Defina como true para substituir o comportamento normal de implantação e fornecer implantação do Google Workspace. A revisão atual permanece implantada enquanto a nova também está sendo implantados. Quando a nova revisão é implantada, a revisão antiga é desimplantada. Usar em em conjunto com o parâmetro delay para controlar quando a implantação é cancelada de segurança.
delay

Para permitir que o processamento da transação seja concluído na revisão existente antes que ela seja não implantados, e elimine a possibilidade de 502 Bad Gateway ou 504 Gateway Timeout errors: defina esse parâmetro com o número de segundos para cancelar a implantação atrasado. Você pode definir quantos segundos quiser, e não há ramificações no desempenho para definir um grande número de segundos. Durante o atraso, não há novas o tráfego será enviado para a revisão antiga.

O padrão é 0 (zero) segundos. Quando override é definido como verdadeiro e delay for 0, a revisão atual será cancelada imediatamente após a nova é implantada. Valores negativos são tratados como 0 (zero) segundos.

Quando override=true é usado com um delay, o 5XX do HTTP 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 desimplantada após o atraso.

Mostrar todas as implantações de uma API Revisão

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

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 da Apigee Borda A menos que você esteja usando o Apigee Edge no local, não será possível alterar essas configurações.

As propriedades importantes contidas na resposta são organization, environment, aPIProxy, name e state. De revisando esses valores de propriedade, você pode confirmar se uma revisão específica de um proxy de API implantados em um ambiente.

Veja todas as implantações no ambiente de teste

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

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

O resultado será o mesmo para todas as APIs implantadas no ambiente de teste.

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

Para buscar uma lista de todas as revisões implantadas atualmente 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, você pode simplesmente usar o método POST com um arquivo JSON ou XML payload, 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 JavaScript Object Notation (JSON). Veja abaixo a resposta JSON padrão para a solicitação POST acima. que criou um proxy de API chamado weatherapi. Uma descrição de cada elemento do perfil da seguinte forma:

{
  "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 uma API proxy:

  • APIProxy revision: a iteração numerada sequencialmente do proxy de API do usuário, conforme mantido pelos serviços da API
  • APIProxy name: o nome exclusivo do proxy de API
  • ConfigurationVersion: a versão dos serviços da API para a qual a API fará o proxy. a configuração está em conformidade
  • CreatedAt: horário em que o proxy de API foi gerado, formatado no horário UNIX
  • CreatedBy: endereço de e-mail do usuário do Apigee Edge que criou a API proxy
  • DisplayName: um nome fácil de usar para o proxy de API.
  • LastModifiedAt: horário em que o proxy de API foi gerado, formatado em UNIX. horário
  • LastModifiedBy: endereço de e-mail do usuário do Apigee Edge que criou a API proxy
  • Policies: uma lista de políticas que foram adicionadas ao proxy de API.
  • ProxyEndpoints: uma lista de ProxyEndpoints nomeados
  • Resources: uma lista de recursos (JavaScript, Python, Java, WebGL) disponíveis para ser executados neste proxy de API
  • TargetServers: uma lista de TargetServers nomeados (que pode ser criada usando o API de gerenciamento de carga), usada 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 POST simples estão vazios. Nos tópicos a seguir, você aprenderá a adicionar e configurar a chave componentes de um proxy de API.

Você também pode ler sobre esses elementos de configuração na referência de configuração do proxy de API.

Script na API

Os tópicos Como usar os proxies de amostra da API, disponíveis no GitHub. Eles oferecem scripts de shell que unem 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. Ambas as abordagens são é demonstrado nos exemplos de scripts abaixo.

Como encapsular a ferramenta de implantação

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

Em seguida, crie um arquivo para armazenar suas credenciais. Os scripts de implantação que você escrever importarão essas configurações, ajudando você a gerenciar centralmente as credenciais de sua conta. Na API Exemplo de plataforma. O nome desse arquivo é 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 encapsulam a implantação .

Agora crie um script de shell que importe essas configurações e as use para chamar a ferramenta de implantação. Para conferir um exemplo, consulte amostras da plataforma de APIs 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 forma:

#!/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}"

Invocar diretamente a API

Pode ser útil escrever scripts de shell simples que automatizem o processo de upload e para implantar proxies de API.

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

#!/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