Tarea de conectores

La tarea Conectores te permite conectarte de manera rápida y segura a los diversos servicios de Google Cloud y otras aplicaciones empresariales desde tu integración mediante los conectores listos para usar disponibles en Integration Connectors.

A fin de obtener una lista de todos los conectores compatibles con la integración de Apigee, consulta Referencia del conector.

Antes de comenzar

  • Asegúrate de tener la función de administrador de Connectors (roles/connectors.admin) de IAM otorgada en tu proyecto de Google Cloud. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.
  • Obtén información sobre los conceptos generales de los conectores de integración.
  • Para conectarte a los servicios de Google Cloud y otras aplicaciones empresariales mediante un conector, asegúrate de haber conectado una cuenta de servicio administrada por el usuario a tu integración. Si tu integración no tiene una cuenta de servicio administrada por el usuario configurada, se usa la cuenta de servicio predeterminada (service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com) de forma predeterminada para la autenticación.
  • Asegúrate de que tu cuenta de servicio tenga el rol de IAM necesario. Para obtener información sobre cómo otorgar roles a una cuenta de servicio, consulta Administra el acceso a las cuentas de servicio.

Agrega una tarea de Connectors

Para agregar la tarea de conectores a tu integración, haz lo siguiente:

  1. En la IU de Apigee, selecciona tu organización de Apigee.
  2. Haz clic en Desarrollar > Integraciones.
  3. Elige una integración existente o crea una nueva haciendo clic en Crear integración.

    Si creas una integración nueva, haz lo siguiente:

    1. Escribe un nombre y una descripción en el diálogo Crear integración.
    2. En la lista de regiones compatibles, elige Región para la integración.
    3. Haz clic en Crear.

    Esto abrirá la integración en la página del diseñador de integración.

  4. En la barra de navegación Diseñador de integración, haz clic en +Agregar una tarea o un activador > Tareas para ver la lista de tareas disponibles.
  5. Haz clic y coloca el elemento Conectores en el editor de integración.

Configura la tarea de conectores

Para configurar una tarea de Connectors, haz lo siguiente:

.

  1. Haz clic en el elemento de tarea Conectores en el diseñador para ver el panel de configuración de tarea de Conectores.

    De forma opcional, haz clic en para cambiar el nombre de la tarea.

  2. Haz clic en Configurar conector.
  3. Puedes seleccionar una conexión existente en la región o crear una nueva. Para configurar una conexión existente, completa los siguientes pasos en la página Editor de tareas de Connectors:
    1. En Seleccionar conectores, selecciona la región de la conexión.
    2. Elige una conexión existente de la lista de conexiones disponibles en la región seleccionada.
    3. Haz clic en Siguiente.
    4. En la lista Tipo, selecciona Entidades o Acciones.
      • Si seleccionas Entidades, se mostrará la lista de entidades compatibles para la conexión en la sección Configurar entidades/acciones. Selecciona una entidad seguida de la Operation que deseas realizar en esa entidad.
      • Si seleccionas Acciones, la lista de acciones compatibles para la conexión se muestra en la columna Set entities/actions. Selecciona una acción para la conexión.
        • Las entidades y las acciones admitidas se basan en el tipo de conector. A fin de obtener una lista de todos los conectores compatibles con la integración de Apigee, consulta Referencia del conector. Para ver las acciones y entidades que se admiten para un conector, consulta la documentación específica del conector.

        Si el conector admite la consulta de SQL personalizada, puedes seleccionar la opción Ejecutar consulta personalizada de la lista Acciones. Por ejemplo, si deseas ver cómo agregar una consulta de SQL personalizada para un conector de BigQuery, visita Ejecuta una consulta de SQL personalizada.

        Para obtener más información sobre las entidades y las acciones, consulta Entidades, operaciones y acciones.

    5. Haz clic en Listo para completar la configuración de conexión y cerrar el panel.

      6. En la siguiente imagen, se muestra un diseño de muestra de la página Editor de tareas de conectores. imagen que muestra el cuadro de diálogo Configurar tarea de conector imagen que muestra el cuadro de diálogo Configurar tarea de conector

Configura las variables de entrada y salida de tareas

En el panel de configuración de tareas de Conectores, se muestran las variables de Entrada de tarea y Salida de tarea que se generan automáticamente según la Entidad y Operación o Acción seleccionada en el cuadro de diálogo Configurar tarea de conector. Estas variables son configurables y se puede acceder a ellas como entradas a la tarea actual o salidas a las tareas o condicionales posteriores en la integración actual.

Para configurar las variables Entrada de tarea o Salida de tarea, haz clic en la variable correspondiente para abrir el panel Configurar variable y realiza los siguientes pasos:

  1. Ingresa el valor de la variable en el campo Valor predeterminado.
  2. (Opcional) Selecciona Usar como entrada para la integración o Usar como salida para la integración.
  3. Haz clic en Guardar.

Para obtener más información sobre los parámetros de entrada y salida de la tarea Conectores, consulta Operaciones de entidades.

Operaciones de entidades

Puedes realizar operaciones CRUD (crear, leer, actualizar y borrar) en las entidades de un conector. Cada una de estas operaciones de entidad tiene un conjunto diferente de parámetros de entrada y salida. En la siguiente tabla, se enumeran los parámetros de entrada y salida de las diversas operaciones de entidad.

Nombre de la operación Parámetros de entrada Los parámetros de resultado
Lista
  • listEntitiesPageSize
  • listEntitiesPageToken
  • listEntitiesSortByColumns
  • filterClause
  • connectorOutputPayload
  • listEntitiesNextPageToken
Obtener entityId connectorOutputPayload
Crear connectorInputPayload connectorOutputPayload
Actualizar
  • connectorInputPayload
  • entityId
  • filterClause
 connectorOutputPayload
Borrar
  • entityId
  • filterClause
 N/A

Parámetros de entrada

En la siguiente tabla, se describen los parámetros de entrada para las diversas operaciones de entidad.

Nombre del parámetro Tipo de dato Descripción
entityId String

Un identificador único de la fila a la que deseas acceder.

Por lo general, entityId es el valor de una clave primaria de una tabla o un conjunto de datos. Si especificas un valor para entityId y la tabla o el conjunto de datos no tienen una columna de clave primaria, la integración informa un error de entorno de ejecución y la tarea Conectores falla.

Por ejemplo, para obtener una fila específica de una tabla de MySQL, entityId es el valor de la clave primaria de la tabla.
connectorInputPayload JSON Los datos reales que se agregarán o actualizarán en una entidad. En el siguiente ejemplo, se muestra el fragmento JSON de los datos de una fila que se agregarán en una tabla: 

{
"employee_first_name": "John",
"employee_emailID": "test-05@test.com"
}

En este ejemplo, employee_first_name y employee_emailID son los nombres de las columnas con los valores correspondientes John y test-05@test.com.
filterClause String Restringe el resultado de las operaciones en función de una condición. Para obtener más información sobre cómo agregar una cláusula de filtro, consulta Agrega un filtro para una operación.
listEntitiesPageSize Integer

Especifica el número de resultados que se deben mostrar en una página.

Una página es una agrupación lógica de los registros en un conjunto de resultados. El concepto de una página es útil cuando esperas una gran cantidad de registros en el conjunto de resultados. Si el conjunto de resultados es grande, la tarea Conectores puede fallar, ya que hay un límite en el tamaño de los datos que la tarea Conectores puede procesar. Si desglosas el conjunto de resultados en fragmentos más pequeños, puedes evitar este problema.

Por ejemplo, si esperas 1,000 registros en tu conjunto de resultados, puedes configurar listEntitiesPageSize como 100. Entonces, cuando la tarea Conectores se ejecuta por primera vez, muestra los primeros 100 registros, los siguientes 100 registros en la segunda ejecución, y así sucesivamente.

listEntitiesPageToken String

Un identificador de página (token) que te permite acceder a una página específica.

Puedes obtener el valor de un token de página desde el parámetro de salida listEntitiesNextPageToken. Debido a que cada página tiene un token único, tienes la flexibilidad de acceder a cualquier página que desees en el conjunto de resultados. Para comprender el uso de este parámetro, también lee la descripción del parámetro de salida listEntitiesNextPageToken.
listEntitiesSortByColumns Arreglo de strings Nombre de la columna según el que deseas ordenar el conjunto de resultados.

Los parámetros de resultado

En la siguiente tabla, se describen los parámetros de salida para las diversas operaciones de entidad.

Nombre del parámetro Tipo de dato Descripción
connectorOutputPayload JSON El resultado de una operación en formato JSON.
listEntitiesNextPageToken String

Un identificador generado por el sistema para una página. Puedes pensar en el token como un puntero mediante el que puedes acceder a una página en particular del conjunto de resultados.

Si dividiste tu conjunto de resultados en varias páginas mediante la configuración del parámetro listEntitiesPageSize, necesitas un mecanismo para navegar por las páginas. El parámetro de salida listEntitiesNextPageToken te permite hacer eso exactamente. Cada vez que se ejecuta la tarea Conectores, el sistema genera un token para la página siguiente y establece el valor de listEntitiesNextPageToken en el token recién generado. Luego, puedes usar este token para acceder a la siguiente página del conjunto de resultados. Para acceder a la página siguiente, debes establecer el parámetro de entrada listEntitiesPageToken en el valor del token de la página siguiente.

Por ejemplo, considera que configuraste el parámetro listEntitiesPageSize como 2 y, luego, cuando la tarea Conectores se ejecuta por primera vez, listEntitiesNextPageToken se configura como el valor del token ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Luego, puedes establecer el parámetro de entrada listEntitiesPageToken en el valor de este token para recuperar la página siguiente en la ejecución posterior de la tarea Conectores.

Si tu conjunto de resultados tiene una gran cantidad de páginas, puedes considerar usar la tarea Para cada bucle a fin de llamar a la tarea Conectores de forma repetida y usar la tarea Asignación de datos para asignar valores de token de forma automática al parámetro de entrada listEntitiesPageToken después de cada ejecución.

Cláusula de filtro para las operaciones de entidad

Puedes restringir los registros que procesa la tarea Conectores mediante la variable Cláusula de filtro que está disponible como Entrada de tarea. Por ejemplo, en el caso de una operación de eliminación, puedes agregar una cláusula de filtro para borrar registros con un orderId específico.

La cláusula de filtro se puede aplicar solo para las siguientes operaciones de entidad:

  • Lista
  • Borrar
  • Actualización

Cuando seleccionas cualquiera de estas operaciones, la sección Entrada de la tarea de la tarea Conectores muestra el campo Cláusula de filtro automáticamente.

Agrega una cláusula de filtro

Para agregar una cláusula de filtro, sigue estos pasos:

  1. Haz clic en el elemento de tarea Conectores en el diseñador para ver el panel de configuración de tarea de Conectores.
  2. Expande la sección Entrada de tarea y haz clic en la variable de string filterClause(conectores).

    Aparecerá el cuadro de diálogo Configurar variable.

  3. Ingresa la cláusula de filtro (después de la cláusula syntax) en el campo Valor predeterminado.
  4. Haz clic en Guardar.

Sintaxis y ejemplos de cláusulas de filtro

Una cláusula de filtro tiene el siguiente formato:

FIELD_NAME CONDITION FILTER_VALUE

Ejemplos

  • OwnerId = '0053t000007941XAAQ'
  • PoNumber < 2345
  • OrderNumber = 00110 AND StatusCode = 'Draft'
  • TotalAmount > 2500
  • ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

Uso de variables en la cláusula de filtro

No puedes usar directamente una variable de integración en una cláusula de filtro. Si deseas usar una variable de integración, primero debes configurar una tarea de asignación de datos para crear una asignación entre la variable de integración y la cláusula de filtro.

En la siguiente tabla, se muestra una asignación de ejemplo entre una variable de integración y la variable filterClause(Connectors):

Entrada Salida
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(') filterClause(Connectors)
En el ejemplo anterior, PRIMARY_KEY_ID = ' se ingresa como un Valor en la fila de entrada.

Creación de conexiones intercaladas

Puedes usar la tarea Conectores para crear directamente una conexión nueva en Conectores de Integration.

Antes de comenzar

Crear conexión nueva

Para crear una conexión nueva a partir de Apigee Integration, sigue estos pasos:

  1. Haz clic en el elemento de tarea Conectores en el diseñador para ver el panel de configuración de tarea de Conectores.
  2. Haz clic en Configurar conector.

    Aparecerá la página Editor de tareas de Connectors.

  3. Omite el campo Región.
  4. Haz clic en Conexión y selecciona la opción Crear conexión en el menú desplegable.
  5. Completa los siguientes pasos en el panel Crear conexión:
    1. En la sección Ubicación, elige la ubicación para la conexión.
      1. Haz clic en Región y selecciona una ubicación de la lista desplegable.
      2. Haz clic en Siguiente.
    2. En el paso Detalles de la conexión, proporciona los detalles sobre la conexión:
      1. Conector: Selecciona el tipo de conector que deseas crear de la lista desplegable. Para obtener más información sobre la lista de conectores compatibles, consulta Todos los conectores de integración.
      2. Versión del conector: elige una versión disponible del tipo de conector seleccionado de la lista desplegable.
      3. Nombre de la conexión: ingresa un nombre para la instancia de conexión nueva.
      4. De manera opcional, ingresa una Descripción para la instancia de conexión.
      5. Marca Habilitar Cloud Logging para almacenar los datos de registro de la instancia de conexión (opcional).
      6. Cuenta de servicio: Selecciona una cuenta de servicio que tenga los roles necesarios.
      7. Haz clic en Configuración avanzada para establecer la configuración del nodo de conexión (opcional).

        Para obtener más información, consulta la documentación de conexión correspondiente en Conectores de integración.

      8. De forma opcional, haz clic en + AGREGAR ETIQUETA para agregar una etiqueta a la conexión en forma de un par clave-valor.
      9. Haz clic en Siguiente.
    3. En el paso Autenticación, proporciona los detalles de autenticación para la conexión.
      1. Los métodos Authentication que se propagan durante este paso se basan en el tipo de conexión que se crea.

        Los diferentes tipos de conexión usan métodos de autenticación distintos. Para obtener más información, consulta la sección Configura la autenticación de la documentación de conexión respectiva en Conectores de integración.

      2. Haz clic en Siguiente.
    4. Revisa: Revisa tus detalles de conexión y autenticación.
    5. Haz clic en Crear.

Prácticas recomendadas

Estrategia de manejo de errores

Una estrategia de manejo de errores de una tarea específica la acción que se debe realizar si la tarea falla debido a un error temporal. Para obtener información sobre cómo usar una estrategia de manejo de errores y conocer los diferentes tipos de estrategias de manejo de errores, consulta Estrategias de manejo de errores.