Cómo usar acurl

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Información

La utilidad acurl(1) proporciona un wrapper práctico alrededor de un comando curl estándar. acurl:

  • Intercambia tus credenciales de Apigee por un token de acceso de OAuth2.
  • Detecta cuándo caducó un token de acceso y usa el token de actualización para obtener un token de acceso nuevo.
  • Pasa ese token en el encabezado Authorization de la solicitud a la API.

Usa tokens de acceso para llamar a los extremos de la API de Edge con OAuth2, incluidos los flujos de trabajo de LDAP y SAML.

Si usas OAuth2 para acceder a la API de Edge, pero no usas acurl, debes obtener un token de acceso y agregarlo al encabezado de la solicitud a la API tú mismo. Una forma de obtener un token de acceso es con la utilidad get_token.

Instala acurl

Antes de poder usar acurl, debes instalarlo.

Sintaxis de acurl

La utilidad acurl usa la siguiente sintaxis:

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

o

acurl API_URL -p PASSCODE

Donde:

Opción ¿Obligatoria? Descripción
API_URL Obligatorio El extremo de la API de Apigee Edge. Para obtener una lista completa de los extremos, consulta la Referencia de la API de Apigee Edge.
USERNAME Opcional. Se requiere una combinación de nombre de usuario y contraseña o una contraseña. Tu nombre de usuario de Apigee, que suele ser la dirección de correo electrónico asociada con tu cuenta de Apigee Debes pasar tu nombre de usuario o una contraseña la primera vez que llames a get_token. No tendrás que volver a pasar tu dirección de correo electrónico hasta que venzan los tokens de acceso y actualización. Si almacenas tokens en caché para más de un usuario, debes especificar tu nombre de usuario en cada llamada.
PASSWORD Opcional. Se requiere una combinación de nombre de usuario y contraseña o una contraseña. La contraseña de tu cuenta de Apigee. Si omites la contraseña, se te solicitará que la ingreses la primera vez que uses acurl y en cualquier llamada posterior sin un token de actualización válido. Si no quieres usar tu contraseña directamente en el comando, puedes usar una contraseña de código de un solo uso en lugar de la contraseña.
MFACODE Opcional Un código de autenticación de varios factores (MFA) temporal de seis dígitos. Este código es obligatorio si usas -u y tienes habilitada la MFA. Se te preguntará si se omite este paso (a menos que esté en el modo de contraseña). Si la MFA no está habilitada o si tienes un flujo con secuencia de comandos, puedes especificar -m "" para evitar mensajes.
PASSCODE Opcional. Se requiere una combinación de nombre de usuario y contraseña o una contraseña. Una contraseña de un solo uso que puedes usar en lugar de una contraseña. Se requiere una contraseña para realizar la autenticación con un IdP de SAML y se puede usar para la autenticación con un IdP de LDAP.

Por ejemplo:

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

Además de las opciones anteriores, acurl acepta todas las opciones de curl. Por ejemplo, puedes pasar encabezados, especificar el verbo HTTP, agregar un cuerpo y habilitar la verbosidad mediante las opciones estándar de curl:

Opción acurl meaning curl meaning
-u username username
-m MFA code max time (debe usar el formato largo --max-time)
-p passcode proxy tunnel (debe usar el formato largo --proxytunnel)
-v verbose verbose
-h help help (debe usar el formato largo --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}'

Una llamada a acurl exitosa muestra los resultados según el extremo de la API de Edge al que llamaste. Además, acurl almacena los tokens de acceso y de actualización en ~/.sso-cli.

Puedes seguir realizando llamadas sin ingresar credenciales (contraseña y MFA opcional o contraseña) hasta que venzan el token de acceso y el de actualización, como se describe en Vencimiento del token.

Cómo migrar desde curl

Si usas curl, la migración a la utilidad acurl es sencilla y elimina la necesidad de codificar credenciales manualmente. Una vez que hayas descargado e instalado la utilidad, puedes reemplazar 

curl -u username
por 
acurl -u username
.

La utilidad acurl codificará tus credenciales y, en ocasiones, te solicitará las credenciales adicionales necesarias para obtener nuevos pares de tokens.

También se puede usar la utilidad acurl a fin de reemplazar curl para los usuarios de máquinas. Consulta OAuth2 para usuarios de máquinas y Usuarios de máquinas en zonas de SAML a fin de obtener más información.

Cómo llamar a acurl por primera vez

La primera vez que llamas a la API con acurl, proporcionas tus credenciales de Apigee (el nombre de usuario y la contraseña de tu cuenta de Apigee o una contraseña) para que acurl pueda intercambiarlas por un token de acceso y un token de actualización.

En el siguiente ejemplo, se muestra una llamada inicial con acurl para obtener detalles sobre una organización mediante el extremo Obtener organización:

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"
}

La utilidad acurl obtiene un token de acceso y lo inserta en la llamada al extremo de la API de Edge:

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

El token de acceso se almacena de forma local en ~/.sso-cli y se usa para llamadas posteriores.

Una vez que venza el token de acceso, acurl usará automáticamente el token de actualización para obtener un token de acceso nuevo. Cuando venza el token de actualización, acurl te pedirá tus credenciales de Apigee.

Esta solicitud obtiene detalles sobre la organización "ahamilton-eval". Para obtener una lista completa de los extremos de la API de Edge, consulta la Referencia de la API de Apigee Edge.

(1) Copyright 2023 Google LLC
La herramienta acurl está disponible como “Software” en virtud del acuerdo que rige el uso de Google Cloud Platform, incluidas las Condiciones Específicas del Servicio disponibles en https://cloud.google.com/terms/service-terms.