Primeiros passos com a API Apigee

Esta é a documentação da Apigee X.
Confira a documentação da Apigee Edge.

A API Apigee pode ser usada para desenvolver e gerenciar APIs de maneira programática com um conjunto de operações RESTful.

É possível usar a API Apigee para integrar o gerenciamento de proxy de API ao ciclo de vida de desenvolvimento de software (SDLC, na sigla em inglês) da sua organização. Um uso comum da API Apigee é 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.

Para mais informações, consulte a API Apigee.

Como ativar a API Apigee

Verifique se você ativou a API Apigee. A maneira mais simples de ativar uma API no projeto é usar o Console do Google Cloud. Veja mais detalhes em Etapa 3: ativar APIs.

Como conseguir um token de acesso OAuth 2.0

A API Apigee é compatível com o OAuth 2.0 para autenticação de usuários. Com o OAuth 2.0, você troca suas credenciais do Google Cloud por um token de acesso que pode ser usado com o objetivo de fazer chamadas seguras para a API Apigee. Depois de receber um token, você não precisa trocar as credenciais novamente até o token expirar.

Receber um token usando as credenciais do Google Cloud

Para receber um token usando suas credenciais do Google Cloud, siga as etapas abaixo:

  1. Autorize o gcloud para acessar o Cloud Platform com suas credenciais de usuário do Google:
    gcloud auth login
  2. Receba um token para a conta ativa no momento:
    export TOKEN=$(gcloud auth print-access-token)
  3. Ao chamar uma API da Apigee, transmita o token de acesso no cabeçalho "Authorization". Exemplo:
    curl "https://apigee.googleapis.com/v1/organizations" -H "Authorization: Bearer $TOKEN"

Receber um token usando uma chave da conta de serviço do Google Cloud

Para receber um token usando uma chave da conta de serviço para autorização:

  1. Gere uma chave para sua conta de serviço usando o Console do GCP, conforme descrito em Como criar e gerenciar chaves de conta de serviço.

    Será feito o download de um arquivo JSON com as credenciais da sua conta de serviço para o computador.

  2. Ao usar suas credenciais do Google Cloud, é possível conseguir um token de acesso OAuth 2.0 para realizar chamadas à API Apigee usando um dos seguintes métodos:

    gcloud

    Use o gcloud para receber um token de acesso do OAuth 2.0, transmitindo o arquivo JSON das credenciais da conta de serviço que você baixou na etapa 1 usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Para mais informações, consulte gcloud auth application-default print-access-token.

    export GOOGLE_APPLICATION_CREDENTIALS=~/sa-credentials-file.json
    gcloud auth application-default print-access-token

    Utilitário oauth2l

    Use oauth2l para receber um token de acesso do OAuth 2.0, transmitindo o arquivo JSON das credenciais da conta de serviço que você baixou na etapa 1.

    oauth2l fetch --json ~/sa-credentials-file.json cloud-platform

    Um token OAuth2.0 é retornado.

  3. Copie o token retornado e armazene-o em uma variável, como TOKEN. Por exemplo:
    export TOKEN=ya29....Ts13inj3LrqMJlztwygtM
  4. Ao chamar uma API da Apigee, transmita o token de acesso no cabeçalho "Authorization". Exemplo:
    curl "https://apigee.googleapis.com/v1/organizations" -H "Authorization: Bearer $TOKEN"

Como definir variáveis de ambiente para solicitações da API Apigee

Os exemplos da API Apigee e da CLI gcloud fornecidos em toda a documentação usam uma ou mais das variáveis de ambiente definidas na tabela a seguir.

Ao definir as variáveis de ambiente com antecedência como valores significativos no seu ambiente, é possível copiar e colar as solicitações de exemplo para executá-las em seu próprio ambiente com modificações mínimas ou nenhuma modificação.

Variável de ambiente Descrição
$API Nome do proxy de API.
$APIPRODUCT Nome do produto da API.
$APP ID de um aplicativo.
$DEVELOPER_EMAIL Endereço de e-mail do desenvolvedor.
$ENV Nome do ambiente, como test ou prod.
$ID ID do recurso.
$KEY Chave do cliente.
$NAME Nome do recurso.
$ORG Sua organização da Apigee.
$REV Número da revisão do proxy de API.
$SHAREDFLOW Nome do fluxo compartilhado.
$TYPE Tipo de recurso.

Como usar o curl

Os exemplos nesta seção usam curl para demonstrar como desenvolver aplicativos usando a API Apigee. curl é uma ferramenta de linha de comando de código aberto para transferência de dados com a sintaxe de URL. Ela é compatível com protocolos comuns, como HTTP e HTTPS.

A tabela a seguir resume as opções de linha de comando curl usadas nos exemplos.

Opção Descrição
-d '{}' --data @filename
--data-binary @filename
Define o corpo da solicitação, que pode ser transmitido diretamente ou ao especificar um nome de arquivo.
-F file=@filename
--form file=@filename
Define dados baseados em formulário que podem ser transmitidos ao especificar um nome de arquivo.
-H
--header
Define um cabeçalho de solicitação.

É necessário transmitir as seguintes informações no cabeçalho da solicitação:

  • Cabeçalho do Authorization: token OAuth 2.0 para autenticação do usuário, conforme descrito em Como receber um token de acesso do OAuth 2.0.
  • Cabeçalho Content-Type: tipo de conteúdo do corpo da solicitação que está sendo enviado ao criar ou atualizar um recurso (POST, PATCH, PUT) usando a API.
-X Especifica o tipo de solicitação (GET, POST etc.).

Exemplo:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apis" \
   -X GET \
   -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0.