Como usar o Acurl

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

O utilitário acurl(1) oferece um wrapper conveniente para um comando curl padrão. acurl:

  • Troca suas credenciais da Apigee por um token de acesso OAuth2.
  • Detecta quando um token de acesso expirou e usa o token de atualização para receber um novo token de acesso.
  • Transmite esse token no cabeçalho Authorization da solicitação de API.

Você usa tokens de acesso para chamar endpoints da API Edge com OAuth2, incluindo fluxos de trabalho LDAP e SAML.

Se você usa o OAuth2 para acessar a API Edge, mas não usa o acurl, é necessário receber um token de acesso e adicioná-lo ao cabeçalho da solicitação de API. Uma maneira de receber um token de acesso é com o get_token utilitário.

Instalar o acurl

Antes de usar o acurl, é necessário instalá-lo.

Sintaxe do acurl

O utilitário acurl usa a seguinte sintaxe:

acurl API_URL -u USERNAME:PASSWORD [-m MFACODE]

ou

acurl API_URL -p PASSCODE

Em que:

Opção Obrigatório? Descrição
API_URL Obrigatório O endpoint de API do Apigee Edge. Para uma lista completa de endpoints, consulte a referência da API Apigee Edge.
USERNAME Opcional. É necessário uma combinação de nome de usuário e senha ou uma senha. Seu nome de usuário da Apigee, que geralmente é o endereço de e-mail associado à sua conta da Apigee. É necessário transmitir seu nome de usuário ou uma senha na primeira vez que você chamar get_token. Não será necessário transmitir seu endereço de e-mail novamente até que os tokens de acesso e de atualização expirem. Se você estiver armazenando tokens para mais de um usuário, especifique seu nome de usuário em cada chamada.
PASSWORD Opcional. É necessário uma combinação de nome de usuário e senha ou uma senha. A senha da sua conta da Apigee. Se você omitir a senha, será solicitado que você a insira na primeira vez que usar o acurl e em todas as chamadas subsequentes sem um token de atualização válido. Se você não quiser usar sua senha diretamente no comando, use uma senha de código único em vez da sua senha.
MFACODE Opcional Um código de autenticação multifator (MFA) temporário de seis dígitos. Esse código é obrigatório se você usar -u e tiver a MFA ativada. Ele será solicitado caso omitido (a menos que esteja no modo de senha). Se você não tiver a MFA ativada ou tiver um fluxo com script, especifique -m "" para evitar solicitações.
PASSCODE Opcional. É necessário uma combinação de nome de usuário e senha ou uma senha. Uma senha única que pode ser usada no lugar de uma senha. Uma senha é necessária ao autenticar com um IDP SAML e pode ser usada para autenticar com um IDP LDAP.

Exemplo:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com -p 424242
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com:mypassw0rd
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com:mypassw0rd -m 123456

Além das opções mostradas acima, acurl aceita todas as curl opções. Por exemplo, é possível transmitir cabeçalhos, especificar o verbo HTTP, adicionar um corpo e ativar a verbosidade usando opções curl padrão:

Opção acurl meaning curl meaning
-u username username
-m MFA code max time (precisa usar o formato longo --max-time)
-p passcode proxy tunnel (precisa usar o formato longo --proxytunnel)
-v verbose verbose
-h help help (precisa usar o formato longo --help) 
acurl -v -X POST -H 'Content-Type: application/json' \
    https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval/apiproducts/myproduct/attributes/attr \
    -u ahamilton@apigee.com -d '{"value":42}'

Uma chamada acurl bem-sucedida retorna resultados com base no endpoint de API Edge que você chamou. Além disso, acurl armazena os tokens de acesso e de atualização em ~/.sso-cli.

É possível continuar fazendo chamadas sem inserir credenciais (senha e MFA opcional ou senha) até que o token de acesso e o token de atualização expirem, conforme descrito em Expiração do token.

Migrar do curl

Se você estiver usando curl, a migração para o utilitário acurl é simples e elimina a necessidade de codificar credenciais manualmente. Depois de fazer o download e instalar o utilitário, você pode substituir: 

curl -u username
 por: 
acurl -u username

O utilitário acurl vai codificar suas credenciais e, ocasionalmente, solicitar as credenciais adicionais necessárias para receber novos pares de tokens.

O utilitário acurl também pode ser usado para substituir o curl para usuários de máquinas. Para mais informações, consulte OAuth2 para usuários de máquinas e Usuários de máquinas em zonas SAML.

Chamar o acurl pela primeira vez

Na primeira vez que você chamar a API com acurl, forneça suas credenciais da Apigee (o nome de usuário e a senha da sua conta da Apigee ou uma senha) para que o acurl possa trocá-las por um token de acesso e um token de atualização.

O exemplo a seguir mostra uma chamada inicial com acurl para receber detalhes sobre uma organização usando o Get organization endpoint:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com':
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

O utilitário acurl recebe um token de acesso e o insere na chamada para o endpoint de API Edge:

curl -H "Authorization: Bearer oauth2_access_token" ...

O token de acesso é armazenado localmente em ~/.sso-cli e usado para chamadas subsequentes.

Depois que o token de acesso expira, acurl usa automaticamente o token de atualização para receber um novo token de acesso. Quando o token de atualização expira, acurl solicita suas credenciais da Apigee.

Essa solicitação recebe detalhes sobre a organização "ahamilton-eval". Para uma lista completa de endpoints da API Edge, consulte a referência da API Apigee Edge.

(1) Copyright 2023 Google LLC
A ferramenta acurl é disponibilizada como "Software" no contrato que rege o uso do Google Cloud Platform, incluindo os Termos específicos do serviço disponíveis em https://cloud.google.com/terms/service-terms.