Você está vendo a documentação do Apigee Edge.
Acesse a
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 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 da API ao SDLC da sua organização. Um uso comum dessa API é escrever scripts ou códigos que implantem proxies de API ou que migrem 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 o de 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 do Edge.
Para usar a API Edge, você precisa se autenticar nas chamadas. Para isso, use um dos seguintes métodos:
- OAuth2 (somente nuvem pública)
- SAML (nuvem pública e privada)
- Autenticação básica (não recomendada; nuvem pública e privada)
Este tópico se concentra no conjunto de APIs usadas para gerenciar proxies de API.
Vídeo:confira este vídeo curto para saber como implantar uma API.
Interação 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 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 durante a iteração. As revisões são numeradas em sequência, 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 e continuar a criar novas revisões desse proxy de API no ambiente de teste. Quando estiver tudo pronto, promova a revisão mais recente do proxy de API no ambiente de teste em vez da 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 avança no ciclo de vida da configuração e implantação iterativa, o número da revisão é incrementado em números inteiros. Usando chamadas de API diretas para implantar, é possível incrementar o número de revisão do proxy de API. Às vezes, ao fazer pequenas alterações, é possível que você não queira incrementar a revisão.
Acessar revisão da API
A versão da API (por exemplo, api.company.com/v1) não muda com frequência. Quando você incrementa a versão da API, isso significa aos 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 da 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 é incrementada automaticamente
sempre que você importa um proxy de API usando a API Importar um proxy de API. Se você
não quiser incrementar a revisão de um proxy de API, use a API Atualizar
revisão do proxy de API. Se você estiver usando o Maven para implantar, use as opções clean ou
update, conforme descrito no arquivo README do
plug-in do Maven.
Por exemplo, chame 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 ambiente
Depois que o proxy de API estiver configurado para receber e encaminhar solicitações corretamente, será possível implantá-lo
em um ou mais ambientes. Normalmente, você itera em proxies de API em test e, quando tudo estiver pronto,
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 fará muito menos
iterações no ambiente de produção.
Não é possível chamar um proxy de API até que ele seja implantado em um ambiente. Depois de
implantar a revisão do proxy de API na produção, é possível publicar o URL prod para desenvolvedores
externos.
Como listar ambientes
Toda organização na Apigee Edge tem pelo menos dois ambientes: test e prod. A diferenciação é arbitrária. O objetivo é oferecer uma área para verificar se o proxy de API
está funcionando corretamente antes de abri-lo para desenvolvedores externos.
Cada ambiente é, na verdade, apenas um endereço de rede, permitindo separar o tráfego entre os proxies de API em que você está trabalhando e aqueles que estão sendo acessados por apps no ambiente 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 só podem ser acessados por proxies de API em execução nesse ambiente.
Visualizar 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. Um proxy
de API que esteja no estado implantado pode ser acessado pela rede nos endereços definidos
no elemento <VirtualHost> desse ambiente.
Como implantar proxies de API
Os proxies de API não podem ser invocados até serem 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. 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á vendo a documentação do Apigee Edge.
Acesse a documentação da
Apigee X. informações
Primeiro, desfaça 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 cancelar a implantação:
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 perfeita (sem inatividade)
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 sobre outra. A implantação do primeiro precisa sempre
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 é revertida: a nova revisão é implantada e, quando ela é
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 parâmetro delay especifica um intervalo de tempo, em segundos, antes do qual a revisão anterior deve ser removida. Assim, as transações em andamento têm um intervalo de tempo para serem concluídas antes de o proxy de API processar a transação ser removido da implantação. Veja a seguir o que ocorre com override=true e o parâmetro delay definido:
- A Revisão 1 está processando as 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 tráfego novo é enviado para a Revisão 1.
- No entanto, a Revisão 1 ainda pode estar processando as transações atuais. Ao definir o
parâmetro
delay(por exemplo, 15 segundos), você dá à Revisão 1 15 segundos para concluir o processamento das transações atuais. - Após o intervalo de atraso, a revisão 1 é cancelada.
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 é Defina como |
delay |
Para permitir que o processamento da transação seja concluído na revisão atual antes que ela seja
removida, e eliminar a possibilidade de O padrão é 0 (zero) segundos. Quando |
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 e a revisão mais antiga será cancelada após o atraso.
Ver todas as implantações de uma revisão de API
Às vezes, é necessário buscar uma lista de todas as revisões atualmente 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 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. Ao
analisar esses valores de propriedade, é possível confirmar se uma revisão específica de um proxy de API foi
implantada em um ambiente.
Confira 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 de revisão 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 é o mesmo para todas as APIs implantadas no ambiente de teste.
Confira todas as implantações na sua organização
Para buscar uma lista de todas as revisões atualmente 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, você pode simplesmente usar o método POST 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 é em
notação de objeto JavaScript (JSON). Veja abaixo a resposta JSON padrão para a solicitação POST acima,
que criou um proxy de API chamado weatherapi. Veja a seguir uma descrição de cada elemento do perfil:
{
"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 APIConfigurationVersion: versão dos serviços da API a que a configuração de proxy de API está em conformidadeCreatedAt: hora em que o proxy de API foi gerado, formatado no horário UNIXCreatedBy: endereço de e-mail do usuário do Apigee Edge que criou o proxy de APIDisplayName: um nome fácil de usar para o proxy de APILastModifiedAt: hora em que o proxy de API foi gerado, formatado no horário UNIXLastModifiedBy: endereço de e-mail do usuário do Apigee Edge que criou o proxy de APIPolicies: uma lista de políticas que foram adicionadas a este proxy de API.ProxyEndpoints: uma lista de ProxyEndpoints nomeadosResources: uma lista de recursos (JavaScript, Python, Java, WebP) disponíveis para execução neste proxy de APITargetServers: uma lista de TargetServers nomeados (que pode ser criada usando a API de gerenciamento), usada em configurações avançadas para fins de balanceamento de cargaTargetEndpoints: uma lista de TargetEndpoints nomeados
Observe que muitos elementos da configuração de proxy de API criados com o método POST simples acima estão vazios. Nos tópicos a seguir, você aprenderá a adicionar e configurar os principais componentes de um proxy de API.
Leia também sobre esses elementos de configuração na referência de configuração do proxy de API.
Scripts na API
A seção 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 exemplo abaixo.
Como encapsular a ferramenta de implantação
Primeiro, verifique se a ferramenta de implantação do Python está disponível no seu ambiente local.
Depois crie um arquivo para guardar suas credenciais. Os scripts de implantação criados importarão essas configurações, o que ajudará você 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 encapsulam 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 de 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 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}"
Invocação direta da API
Pode ser útil escrever scripts de shell simples que automatizem o processo de upload e de implantação de proxies de API.
O script abaixo invoca diretamente a API de gerenciamento. Ele cancela a implantação da revisão atual do
proxy de API que você está atualizando, cria um arquivo ZIP no diretório /apiproxy
que contém os arquivos de configuração de 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