Saltar al contenido

Registro de conectores para conectores del SDK de Conectores

Introducción

Todos los conectores utilizados en Jitterbit iPaaS deben estar registrados, y los desarrolladores que utilizan el SDK de Conectores de Jitterbit necesitan registrar sus conectores antes de construir y empaquetarlos.

Cada conector y cada una de sus actividades recibe un ID único de Jitterbit que lo identifica de todos los demás conectores y sus actividades.

Antes de construir un archivo JAR de conector, necesitarás obtener estos valores para cada conector:

  • ID del conector
  • Clave del conector
  • Secreto del conector
  • ID de entidad de punto final
  • ID de actividad inicial
  • ID de actividad final

API REST para registrar conectores

Para obtener estos valores, utiliza la API del Administrador de Conectores de Jitterbit, disponible como una colección de Postman incluida en el conector de Dropbox en postman/JitterbitConnectorManagerAPI.collection.json.

La colección proporciona estas funciones ("solicitudes"):

  • Iniciar sesión como usuario
  • Registrar un conector
  • Listar conectores registrados
  • Eliminar un conector registrado
  • Validar clave/secreto del conector

Configurar la API en Postman

Antes de ejecutar la API REST, importa las variables de entorno desde postman/JitterbitConnectorManagerAPIEnvVariables.json en Postman y asócialas con la colección.

Edita el entorno de Postman e ingresa valores para las claves host (según lo definido por tu región; consulta Encontrar mi región), email (tu nombre de usuario de Harmony), password (tu contraseña de Harmony), orgID de Harmony, y el nombre, versión y descripción del conector. Las otras variables de entorno (authToken, connectorID, key y secret) serán ingresadas por Postman a medida que utilices las APIs:

image

El nombre bajo el cual se registra el conector debe coincidir con el valor en el archivo adapter.json utilizado para describir la interfaz de usuario. (Para detalles sobre la interfaz de usuario de Integration Studio y el archivo adapter.json, consulta Implementación de Conectores y Componentes de UI del SDK de Conectores.)

Al inicio de una sesión de ejecución de las funciones de la API, siempre se debe ejecutar primero la función Log In User para obtener un authenticationToken. Este token será retenido por Postman y se utilizará para solicitudes posteriores en la misma sesión.

Registrar un conector

Para registrar un conector, ejecuta estas dos APIs en orden desde Postman:

  1. Log In User

    image

  2. Register a Connector

    image

La respuesta devuelta por la API Register a Connector contiene las claves y valores que son necesarios para que el manifiesto del conector complete el registro del conector. Deberías recibir una respuesta como la siguiente:

{
  "status": true,
  "operation": "Register a connector",
  "id": "3691",
  "key": "41384368...d871d2d7ec9",
  "secret": "bb574709...7f2f79f60c49",
  "endpointEntityId": "20101",
  "functionEntityStartId": "20102",
  "functionEntityEndId": "20200"
}

Como se puede ver en este ejemplo, se ha registrado un conector, tiene un ID de 3691, tiene un ID de entidad de punto final de 20101, y puede tener IDs de entidad de actividad de función que van desde 20102 hasta 20200. También se han devuelto una clave y un secreto.

API de Registro de Conector Claves del Archivo de Manifiesto
key Jitterbit-Connector-Key
secret Jitterbit-Connector-Secret
endpointEntityId Jitterbit-Connector-Endpoint-EntityTypeId
functionEntityStartId Jitterbit-Activity-EntityTypeId-<first_activity>
functionEntityEndId Jitterbit-Activity-EntityTypeId-<last_activity>

La clave y el secreto devueltos se convertirán, como se muestra en la tabla anterior, en el Jitterbit-Connector-Key y Jitterbit-Connector-Secret en el manifiesto para el contenedor.

Al conector se le ha asignado un ID de punto final y un rango de IDs de punto final de actividad (función), desde el primero hasta el último. En el caso del conector de Dropbox, que tiene cuatro actividades (Fetch File, Get File, Process File y Put File), se asignarían IDs individuales a cada actividad de manera que caigan dentro del rango asignado. Se puede asignar un máximo de 99 actividades a un conector individual.

Los conectores se pueden registrar en cualquier momento del proceso de desarrollo (ya sea mientras se formula el diseño o justo antes de empaquetar). Sin embargo, es una buena práctica hacerlo lo antes posible, en caso de que haya algún problema en su registro o en la obtención de las claves necesarias.

Lista de conectores registrados

Utiliza este método para ver todos los conectores actualmente registrados en una organización. Utiliza las variables host y orgId del entorno de Postman.

Desde Postman, ejecuta estas dos APIs en orden:

  1. Log In User (requerido solo si no lo has ejecutado ya en la sesión actual; consulta Registrando un conector)

  2. List Registered Connectors

    Esta captura de pantalla muestra la lista de conectores registrados devuelta para la organización actual:

    image

Eliminar un conector registrado

Si es necesario, puedes eliminar un conector registrado. Para eliminar un conector, se requiere que tengas tanto la organización (orgId) a la que pertenece como el ID del conector (connectorId). El ID del conector se mostró cuando se registró el conector y se puede encontrar utilizando el método Lista de conectores registrados para ver todos los conectores actualmente registrados en una organización.

Desde Postman, ejecuta estas dos APIs en orden:

  1. Log In User (requerido solo si no lo has ejecutado ya en la sesión actual; consulta Registrando un conector)

  2. Delete a Registered Connector

    Esta captura de pantalla muestra el mensaje devuelto si el conector especificado por el connectorId fue eliminado con éxito:

    image

Validar una clave/secreto de conector

Puedes validar el nombre, la clave y el secreto de un conector registrado. Ingresa los valores en las variables de entorno de Postman connectorName, key y secret, y luego utiliza esta API. Ten en cuenta que los tres elementos son requeridos, incluido el nombre del conector, para validar la clave y el secreto del conector.

Estos valores se mostraron cuando se registró el conector y se pueden encontrar utilizando el método de Listar conectores registrados para ver todos los conectores actualmente registrados en una organización.

Desde Postman, ejecuta estas dos API en orden:

  1. Iniciar sesión de usuario (requerido solo si no lo has ejecutado ya en la sesión actual; consulta Registrando un conector)

  2. Validar clave/secreto del conector

    Esta captura de pantalla muestra el mensaje devuelto si el conector especificado por el connectorId fue validado con éxito (la clave y el secreto son correctos para el conector nombrado):

    image

Manifiesto del conector

Como parte de la construcción de Maven, estos atributos deben estar presentes como parte del MANIFEST.MF para indicar que es un conector de Harmony. Usando el manifiesto del conector de Dropbox, con sus actividades—Obtener archivo, Poner archivo, Procesar archivo y Obtener archivo—y los valores para endpointEntityId, functionEntityStartID y functionEntityEndID como se muestra arriba, podrías construir un manifiesto como:

Author: <author_name>
Version: 1.0.0
Jitterbit-Connector-Key: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Jitterbit-Connector-Secret: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Jitterbit-Connector-Endpoint-Id: 20101
Jitterbit-Connector-UI: adapter.json
Jitterbit-Activity-EntityTypeId-fetch: 20102
Jitterbit-Activity-EntityTypeId-put: 20103
Jitterbit-Activity-EntityTypeId-process: 20104
Jitterbit-Activity-EntityTypeId-get: 20105
Jitterbit-ConnectorClassLoader-Version: 1.0.0
Class-Path: lib/dropbox-core-sdk-3.0.6.jar
Clave del archivo de manifiesto Descripción
Autor Reemplaza <author_name> con tu nombre.
Versión Establece el identificador de versión semántica apropiado (por ejemplo, versión 1.0.0).
Jitterbit-Connector-* Consulta la sección anterior sobre API REST para registrar conectores para obtener detalles sobre cómo obtener estos atributos utilizando una API REST.
Jitterbit-Activity-* Consulta la sección anterior sobre API REST para registrar conectores para obtener detalles sobre cómo obtener estos atributos utilizando una API REST.
Jitterbit-Connector-UI (Opcional) Proporciona el archivo que contiene las declaraciones de la interfaz de usuario para el conector. El nombre predeterminado es adapter.json.
Jitterbit-Connector-Factory-Class (Opcional) Proporciona la clase de fábrica que crea una instancia de JitterbitConnector. Si no se proporciona entonces debes usar una anotación @Connector en la clase de entrada que implemente la interfaz JitterbitConnector o extienda la clase abstracta BaseJitterbitConnector.
Jitterbit-ConnectorClassLoader-Version (Opcional) La versión actual es 1.0.0. Especificar este cargador de clases previene colisiones al cargar archivos Java. Disponible con versiones de agente 10.68 y posteriores.
Class-Path Una lista de URLs separadas por espacios de cualquier JAR de terceros que componga el conector. En el ejemplo anterior, contiene el JAR del SDK de Dropbox.

En este ejemplo de la sección anterior, el ID del punto final del conector era 20101, el ID de la actividad inicial era 20102, y el ID de la actividad final era 20200. La actividad Fetch File puede asignarse 20102, la actividad Put File puede asignarse 20103, la actividad Process File puede asignarse 20104, y la actividad Get File puede asignarse 20105. Se pueden registrar y asignar IDs a actividades adicionales si es necesario, siempre que se encuentren dentro del rango asignado.

Cambiar un conector registrado

Si realizas cambios en un conector registrado, y especialmente en uno que ha sido desplegado en producción, ten en cuenta cómo los cambios pueden y afectarán a los proyectos existentes que utilizan ese conector.

Cuando un conector se despliega en Harmony, los IDs especificados en el archivo MANIFEST.MF se revisan para asegurar que todas las instancias del conector en diferentes regiones sean consistentes.

En general, sigue estas prácticas para asignar actividades en el MANIFEST.MF:

  • Siempre asigna las actividades en orden e incrementa cada actividad en 1. No dejes ningún espacio.
  • Si sabes que agregarás una actividad más tarde, es mejor agregarla antes y crear un código provisional para ella en los archivos Java como no-ops. Estos pueden completarse cuando estén listos.
  • Las actividades pueden ocultarse al no incluirlas en el archivo adapter.json.
  • Una vez asignadas y desplegadas, no cambies el orden de las actividades como se indica en el MANIFEST.MF.
  • Agrega cualquier nueva actividad después de la última actividad, en la siguiente posición disponible.
  • No elimines una actividad existente del MANIFEST.MF. En su lugar, elimina la actividad del adapter.json, y crea un código provisional en los archivos Java para que sea no-op.

Eliminar una actividad existente que esté en medio de una lista de actividades puede resultar en el desplazamiento de los IDs de las otras actividades y una actividad Update convirtiéndose en una actividad Create en proyectos existentes.