Cómo usar acurl

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

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

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

Usa tokens de acceso para llamar a extremos de la API de Edge con OAuth2, lo que incluye 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. Una forma de obtener un el 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

Aquí:

Opción ¿Obligatoria? Descripción
API_URL Obligatorio El extremo de la API de Apigee Edge Para obtener una lista completa de 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 necesitarás pasar tu correo electrónico dirección de nuevo hasta que caduquen 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 un código de acceso. La contraseña de tu cuenta de Apigee. Si omites la contraseña, se te pedirá que hagas lo siguiente: ingrésalo la primera vez que uses acurl y en cualquier llamada posterior sin un nombre token de actualización. Si no quieres usar tu contraseña directamente en el comando, puedes usar un de código de uso único en lugar de tu contraseña.
MFACODE Opcional Una autenticación temporal de seis dígitos de varios factores (MFA). Este código es obligatorio si usas -u y tienes habilitada la MFA. Se te solicitará si lo omite (a menos que estés en modo de contraseña). Si no tienes habilitada la MFA o tienes un flujo de secuencias de comandos, puedes especificar -m "" para evitar las indicaciones.
PASSCODE Opcional. Se requiere una combinación de nombre de usuario y contraseña o una contraseña. Un código de acceso de un solo uso que puedes usar en lugar de una contraseña Se requiere una contraseña cuando se realiza la autenticación con un IdP de SAML y se puede usar para autenticarse 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 que se muestran arriba, acurl acepta todas las opciones de curl. Por ejemplo, puedes pasar encabezados, especificar el verbo HTTP, agregar un cuerpo y habilitar la verbosidad con las opciones estándar de curl:

Opción acurl meaning curl meaning
-u username username
-m MFA code max time (debes usar formato largo --max-time)
-p passcode proxy tunnel (debes usar formato largo --proxytunnel)
-v verbose verbose
-h help help (se 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 resultados según el extremo de la API de Edge que llamado. 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 bien un código de acceso) hasta que venza el token de acceso y el token de actualización, como se describe en Vencimiento de tokens.

Cómo migrar desde curl

Si usas curl, la migración a la utilidad acurl es sencilla y elimina la necesidad de codificar las credenciales de forma manual. Una vez que hayas descargado e instalado la utilidad, podrás hacer lo siguiente: reemplazar: 

curl -u username
 con: 
acurl -u username

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

La utilidad acurl también se puede usar para reemplazar curl para los usuarios de máquinas. Para obtener más información, consulta OAuth2 para usuarios de máquinas y Usuarios de máquinas en zonas de SAML.

Cómo llamar a acurl por primera vez

La primera vez que llames a la API con acurl, proporciona 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 con el extremo Get organization:

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 localmente en ~/.sso-cli y se usa para las llamadas subsiguientes.

Después de que venza el token de acceso, acurl usa automáticamente el token de actualización para obtener un nuevo token de acceso. Cuando venza el token de actualización, acurl te solicitará tus credenciales de Apigee.

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

(1) Derechos de autor 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.