Comienza a usar Apigee Integration

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

En esta guía de inicio rápido, se muestra cómo crear una integración de muestra en Apigee. En los pasos que se indican a continuación, se describe cómo configurar el activador, las tareas, los perímetros, las variables y las asignaciones de datos necesarias para ejecutar una integración completa. En esta guía de inicio rápido, recuperarás una lista de productos de un extremo URL, transformarás los datos en un formato usable y envías la lista resultante en un correo electrónico, todo desde el diseñador de integración.

Habilita las integraciones

Para habilitar la función de integraciones en Apigee, puedes crear una organización de evaluación para pruebas o pagar las integraciones si tienes una suscripción a Apigee.

Habilita las integraciones en una organización de evaluación

Una organización de evaluación te permite probar la función de integraciones de Apigee sin que se te facture por el uso. Para comprender cómo aprovisionar una organización de evaluación, consulta Aprovisiona una organización de evaluación. Usa una organización de evaluación si tu objetivo es solo explorar y jugar con la característica de integración, ya que las integraciones creadas en eval org tienen algunas limitaciones. Para obtener más información, consulta la página sobre cómo comparar la evaluación y las organizaciones pagas.

La organización de eval ya tendrá habilitadas las integraciones y el complemento de conectores. El complemento de conector es necesario para acceder a fuentes de datos externas desde tus integraciones. Por lo tanto, después de aprovisionar la organización de evaluación, solo debes habilitar las siguientes API para la organización de evaluación, y puedes usar la función de integraciones.

  • API de Cloud Integrations (integrations.googleapis.com)
  • API de Connectors (connectors.googleapis.com)

Después de habilitar las API, puedes comenzar a crear integraciones. Para obtener más información, consulta la sección Crea una integración nueva.

Habilita las integraciones en una organización pagada

Si quieres usar integraciones de Apigee sin limitaciones, puedes pagar las integraciones. La integración de Apigee está disponible como un servicio de complementos para tu suscripción. Como primer paso, comunícate con el equipo de asistencia de Apigee para agregar Integration y Connectors a tu suscripción. Después de agregarlas a tu suscripción, realiza las siguientes tareas:

  1. Habilita las siguientes API:
    • API de Apigee (apigee.googleapis.com)
    • API de Cloud Integrations (integrations.googleapis.com)
    • API de Secret Manager (secretmanager.googleapis.com)
    • API de Connectors (connectors.googleapis.com)

    Para obtener información sobre cómo habilitar las API, consulta Habilita servicios.

  2. Habilita los complementos de Integration y Connectors para tu organización de Apigee.
    • Si creas una nueva organización para usar con Integration, ejecuta el siguiente comando:

      curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" -d '{"name":"${ORG_ID}", "analyticsRegion":"us-west1", "authorized_network":"${NETWORK_ID}", "runtimeType":"CLOUD", "runtimeDatabaseEncryptionKeyName":"${ENCRYPTION_KEY_NAME}", "addonsConfig": {"integrationConfig": {"enabled": true}, "connectorsPlatformConfig":{"enabled":true}}}' "https://apigee.googleapis.com/v1/organizations?parent=projects/${PROJECT_ID}"
    • Si usas una organización existente, ejecuta el siguiente comando:

      curl -H "Authorization: Bearer $TOKEN" -H "content-type:application/json" "https://apigee.googleapis.com/v1/organizations/${ORG_ID}:setAddons" -XPOST -d '{"addonsConfig":{"integrationConfig":{"enabled":true},"connectorsPlatformConfig":{"enabled":true}}}'

    Para verificar si los complementos se habilitaron correctamente, ejecuta el siguiente comando:

    curl -H "Authorization: Bearer $TOKEN"  -H "content-type:application/json" "https://apigee.googleapis.com/v1/organizations/${ORG_ID}"

    Cuando ejecutes el comando, debe aparecer un mensaje similar al siguiente:

    {
      "name": "Test....",
      "createdAt": "1615483867669",
      "lastModifiedAt": "1615483873468",
      …...
      "addonsConfig": {
        "integrationConfig": {
          "enabled": true,
        "connectorsPlatformConfig": {
          "enabled": true
        }
      }
    }
  3. Otorga los roles y permisos de IAM necesarios al agente de servicio de Apigee (service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com).

    Para otorgar esos permisos, haz lo siguiente:

    1. En Cloud Console, ve a la página IAM y administración > IAM.
    2. Selecciona Incluir asignaciones de roles proporcionadas por Google. Esto muestra el agente de servicio de Apigee junto con otros principales.
    3. Otorga los roles necesarios al agente de servicio de Apigee.
    4. Haz clic en Guardar.
  4. Otorga los siguientes roles a tu proyecto de Google Cloud:
    • Editor
    • Administrador de la organización de Apigee
    • Administrador de integraciones de Apigee
    • Administrador del conector

Cómo crear una integración nueva

Para crear una integración nueva, sigue estos pasos:

  1. Ve a la IU de Apigee y accede.
  2. Selecciona tu organización mediante el menú desplegable que se encuentra en la esquina superior izquierda de la IU.
  3. Haz clic en Desarrollar > Integraciones.
  4. Haz clic en Create new (Crear nueva).
  5. Ingresa un nombre y una descripción en el diálogo Crear integración. Por ejemplo, my-test-integration.
  6. En la lista de regiones compatibles, selecciona Región para la integración.
  7. Haz clic en Crear para abrir el diseñador de integración.

Configura un activador

Se requieren activadores para iniciar la secuencia de tareas que conforman una integración. Se puede usar cualquier activador disponible para iniciar una integración. Para la guía de inicio rápido, usa el Activador de API.

Para configurar el activador de API, haz lo siguiente:

  1. En el diseñador de integración, selecciona Agregar una tarea/activador > Activadores para ver una lista de los activadores disponibles.
  2. Arrastra el elemento Activador de API al diseñador de integración.
  3. Haz clic en el elemento Activador de API en el diseñador para abrir el panel de configuración del activador.
  4. La integración de Apigee propaga automáticamente la Etiqueta, el Nombre y el ID del activador. El ID del activador se genera a partir de máquinas y no puedes editar el valor. Sin embargo, puedes editar el valor de las propiedades Etiqueta y Nombre del activador.

    Los cambios en las propiedades se guardan automáticamente.

Agrega y configura tareas

Una tarea es un conjunto ejecutable de pasos que puede tomar variables como entradas y generar variables como resultados. Al igual que con los activadores, se puede usar cualquier tarea disponible en una integración. En esta guía de inicio rápido, se usan las tareas Llamar a extremo REST, Asignación de datos y Enviar correos electrónicos. Los detalles de configuración para cada tarea se describen en los pasos que se indican a continuación.

Configura la tarea Call REST Endpoint

Configura la tarea Llamar al extremo REST:

  1. Selecciona Agregar una tarea/activador > Tareas para ver una lista de tareas disponibles.
  2. Arrastra el elemento Llamar al extremo de REST al diseñador de integración.
  3. Haz clic en el elemento Llamar a extremo de REST en el diseñador para abrir el panel de configuración de la tarea. Establece las siguientes propiedades:
    • Etiqueta: Ingresa un nombre personalizado para esta tarea. Por ejemplo, ingresa Call REST Endpoint Task.
    • Autenticación: Para esta guía de inicio rápido, no se requiere un perfil de autenticación. Para obtener más información sobre el uso de perfiles de autenticación para otros casos de uso, consulta Crea perfiles de autenticación en la integración de Apigee.
    • ENTRADA DE TAREAS: ingresa los detalles para llamar al extremo de REST. La información ingresada aquí se usa como entrada para la tarea Llamar al extremo REST. Ingresa la siguiente información:
      • URL base del extremo: ingresa https://apigee-pm4-prod.apigee.net/v1/hipsters/products. Este extremo muestra un array de objetos de productos, cada uno con un id, name, description, picture, price y un array de categories.
      • Método HTTP: Selecciona GET mediante la lista del menú desplegable.
      • Encabezados HTTP adicionales: Ingresa los encabezados adicionales necesarios para acceder al extremo. Para esta guía de inicio rápido, sigue estos pasos:
        • Ingresa x-apikey en el campo Clave de encabezado HTTP.
        • Ingresa H7WpkpvdCAC2jSffbmKpQLVduxC6nOO9 en el campo Valor.
    • SALIDA DE TAREAS: Aquí la integración con Apigee propaga tres variables para contener el resultado de los datos de respuesta y que llama al extremo REST:
      • responseHeader(Llamar al extremo REST): Esta variable contiene los datos del encabezado de respuesta asociados con la tarea Llamar al extremo REST. Los datos variables son del tipo String (STR).
      • responseBody(Llamar al extremo REST): Esta variable contiene los datos del cuerpo de la respuesta asociados con la tarea Llamar al extremo REST. Los datos variables son del tipo String (STR).
      • responseStatus(Llamar al extremo REST): Esta variable contiene los datos de estado de la respuesta asociados con la tarea de Llamar al extremo REST. Los datos variables son del tipo String (STR).
    • Para ver los detalles de cada variable, haz clic en el nombre de la variable en el panel de configuración de tareas. En esta guía de inicio rápido, deja los valores predeterminados para cada una de estas variables.
    • Los campos restantes deben contener los siguientes valores predeterminados:
      • Seguir los redireccionamientos: True
      • Error de generación: False
      • Volver a intentar en caso de error
        • Cuando la integración se ejecuta de forma síncrona: None
        • Cuando la integración se ejecuta de forma asíncrona: None

    Los cambios en las propiedades se guardan automáticamente.

    La configuración completa debería coincidir con la siguiente figura:

    Activador de Llamar al extremo REST

  4. Agrega una conexión perimetral del elemento activador de API al elemento Llamar a extremo de REST. Para ello, coloca el cursor sobre un punto de control en el elemento Activador de API, luego haz clic en una línea y arrástrala hasta un punto de control en el elemento de tarea Llamar a extremo de REST. Los puntos de control y la línea perimetral se mostrarán en color amarillo, como se muestra en la siguiente imagen:

    Diseñador de integración que muestra una conexión perimetral

    El perímetro denota el flujo de control del activador de API a la tarea Llamar al extremo de la REST.

Configura la tarea Asignación de datos

Para configurar la tarea de asignación de datos, haz lo siguiente:

  1. Selecciona Agregar una tarea/activador > Tareas para ver una lista de tareas disponibles.
  2. Arrastra el elemento Asignación de datos al diseñador de integración.
  3. Haz clic en la tarea Asignación de datos en el diseñador para abrir el panel de configuración de la tarea.
  4. Haz clic en Abrir editor de asignación de datos.

    El Editor de asignación de datos te permite asignar variables de entrada a las variables de salida deseadas con las funciones de transformación disponibles. Entonces, el resultado está disponible como una variable para cualquier otra tarea o activador de integración. Si deseas obtener más detalles para pasar datos como variables, consulta Usa variables en la integración de Apigee.

    En esta guía de inicio rápido, sigue estos pasos para crear una asignación con responseBody(Llamar al extremo REST) como entrada:

    1. Arrastra el chip responseBody de la lista Variables del lado izquierdo del editor al primer campo Entrada.
    2. Haz clic en + Agregar función en el chip responseBody para ver la lista desplegable de funciones disponibles.
    3. Puedes aplicar varias funciones de asignación de datos para transformar los datos en la variable de entrada. En este caso, puedes convertir la carga útil en JSON y, luego, iterar sobre el array de respuestas para obtener la lista de nombres de productos necesarios en las notificaciones por correo electrónico. Haz clic en el símbolo + Agregar función en la variable responseBody para abrir la lista de funciones disponibles. Usa las siguientes funciones:
      • Selecciona TO_JSON() para convertir la string responseBody en JSON.
      • Vuelve a hacer clic en el símbolo + Agregar función en el chip de variable responseBody para seleccionar y encadenar la función GET_PROPERTY(). Esta función extraerá una propiedad de la carga útil JSON. Pasa la propiedad products.name como parámetro para esta función. Esto mostrará una lista de SOLO los nombres de los productos, sin otra información sobre ellos. La función se debe leer de la siguiente manera:
        responseBody(Call REST Endpoint).TO_JSON().GET_PROPERTY(products.name)
      • Si necesitas quitar o borrar una función, haz clic en el símbolo -. Esta acción quitará la función que recién se agregó.
    4. Haz clic en el primer campo de la columna Salida a fin de crear una variable nueva para conservar el valor de los datos transformados. Completa los siguientes campos:
      • Nombre: Ingresa JSONProdNameList.
      • Tipo de datos: JSON
      • Marca Usar como salida de la integración.
      • Haz clic en Crear para crear la variable y cerrar el panel. La nueva variable JSONProdNameList aparecerá en la lista Variables del lado izquierdo del editor de asignación de datos.
    5. En el editor de asignación de datos, haz clic en la X para guardar la asignación y cerrar el editor.
    6. La asignación completa debería aparecer como se muestra en la siguiente figura:

      Imagen de la asignación de datos y las variables completados

  5. Agrega una conexión perimetral desde el elemento Llamar al extremo REST al elemento asignación de datos coloca el cursor sobre un punto de control en el elemento Llamar al extremo REST. Luego, haz clic en una línea y arrástrala hasta un punto de control en el elemento de tarea Asignación de datos. El borde denota el flujo de control de la tarea Llamar a extremo de REST a la tarea Asignación de datos.

Configura la tarea de enviar correos electrónicos

Para configurar la tarea Enviar correo electrónico, haz lo siguiente:

  1. Selecciona Agregar una tarea/activador > Tareas en el diseñador de integración para ver la lista de tareas disponibles.

    En este paso, usa la tarea Enviar correo electrónico.

  2. Arrastra el elemento Enviar correo electrónico al diseñador de integración.
  3. Haz clic en el elemento Enviar correo electrónico en el diseñador para abrir el panel de configuración de la tarea. Establece las siguientes propiedades:
    • Destinatarios: Ingresa tu dirección de correo electrónico. Usa este correo electrónico para confirmar que la integración se completó correctamente.
    • Asunto: Ingresa Email from Apigee Integrations.
    • Cuerpo del correo electrónico: selecciona la variable JSONProdNameList creada antes en la tarea Asignación de datos.
    • Las opciones restantes pueden dejarse en la configuración predeterminada.

    Los cambios en las propiedades se guardan de forma automática.

    La configuración completa debería coincidir con la siguiente figura:

    Configuración de tareas por correo electrónico

  4. Agrega una conexión perimetral del elemento Asignación de datos al elemento de Enviar correo electrónico cuando colocas el cursor sobre un punto de control del elemento Asignación de datos, luego, haz clic en una línea y arrástrala hasta un punto de control en el elemento de tarea Enviar correo electrónico. Los puntos de control y la línea perimetral se mostrarán en amarillo. El perímetro denota el flujo de control de la tarea de Asignación de datos a la tarea de Enviar correo electrónico.

Prueba la integración

Para probar la nueva integración, sigue estos pasos:

  1. Haz clic en el botón Publicar en la barra de herramientas del diseñador de integración. La publicación de la integración activa el botón Test en la barra de herramientas.
  2. Haz clic en Test y, luego, selecciona API Trigger.
  3. En el cuadro de diálogo Confirm Publish and Test, haz clic en Publish & Test.

Para obtener más información sobre las pruebas, consulta Prueba las integraciones.

Cuando la compilación se completa de forma correcta, la integración envía un correo electrónico con la lista del nombre del producto a la dirección de correo electrónico especificada en la tarea Enviar correo electrónico. Confirma la recepción del correo electrónico en tu cliente de correo electrónico.

El correo electrónico que envió la integración debe contener un cuerpo similar al siguiente:

["Vintage Typewriter", "Vintage Camera Lens", "Home Barista
Kit", "Terrarium", "Film Camera", "Vintage Record Player", "Metal Camping
Mug", "City Bike", "Air Plant"]

Además de verificar el contenido del correo electrónico, puedes inspeccionar los registros para ver el estado y la carga útil de una integración determinada. Para ver los registros, haz lo siguiente:

  1. Haz clic en Registros en la barra de herramientas del diseñador de integración.
  2. En la página Registros de ejecución, puedes ver los detalles de cada intento para ejecutar una integración. Cada entrada incluye detalles para el intento de ejecución, incluidos los siguientes:
    • Nombre de la integración
    • ID de ejecución
    • Estado
    • Hora de inicio
    • Duration
    • Versión de la integración
    • ID de activador
  3. Haz clic en la flecha desplegable (>) junto a la integración ejecutada para ver una lista expandida de tareas y variables en la integración, junto con el estado de la tarea y las cargas útiles de la variable.

¡Felicitaciones! Configuraste e implementaste de forma correcta una integración con la integración de Apigee.

¿Qué sigue?