Registro de conectores para conectores do SDK de Conector

Introdução

Todos os conectores usados no Jitterbit iPaaS precisam ser registrados, e os desenvolvedores que utilizam o SDK de Conector do Jitterbit devem registrar seus conectores antes de construí-los e empacotá-los.

Cada conector e cada uma de suas atividades recebe um ID único do Jitterbit que o identifica em relação a todos os outros conectores e suas atividades.

Antes de construir um arquivo JAR do conector, você precisará obter esses valores para cada conector:

• ID do Conector
• Chave do Conector
• Segredo do Conector
• ID da entidade de endpoint
• ID da atividade inicial
• ID da atividade final

API REST para registrar conectores

Para obter esses valores, use a API do Gerenciador de Conectores do Jitterbit, disponível como uma coleção do Postman incluída no conector do Dropbox em postman/JitterbitConnectorManagerAPI.collection.json.

A coleção fornece essas funções ("requisições"):

• Fazer Login
• Registrar um Conector
• Listar Conectores Registrados
• Deletar um Conector Registrado
• Validar Chave/Segredo do Conector

Configurar a API no Postman

Antes de executar a API REST, importe as variáveis de ambiente de postman/JitterbitConnectorManagerAPIEnvVariables.json para o Postman e associe-as à coleção.

Edite o ambiente do Postman e insira valores para as chaves host (conforme definido pela sua região; veja Encontrar minha região), email (seu nome de usuário do Harmony), password (sua senha do Harmony), orgID do Harmony e o nome, versão e descrição do conector. As outras variáveis de ambiente (authToken, connectorID, key e secret) serão inseridas pelo Postman à medida que você usar as APIs:

O nome sob o qual o conector é registrado deve corresponder ao valor no arquivo adapter.json usado para descrever a interface do usuário. (Para detalhes sobre a interface do usuário do Integration Studio e o arquivo adapter.json, veja Implementação de Conector e Componentes da UI do SDK de Conector.)

No início de uma sessão de execução das funções da API, sempre execute primeiro a função Log In User para obter um authenticationToken. Este token será retido pelo Postman e usado para solicitações subsequentes na mesma sessão.

Registrar um conector

Para registrar um conector, execute essas duas APIs na ordem a partir do Postman:

1. Log In User

   

2. Register a Connector

   

A resposta retornada pela API Register a Connector contém as chaves e valores necessários para o manifesto do conector completar o registro do conector. Você deve receber uma resposta como:

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

Como pode ser visto neste exemplo, um conector foi registrado, tem um ID de 3691, possui um ID de entidade de ponto de extremidade de 20101, e pode ter IDs de entidades de atividade de função variando de 20102 a 20200. Uma chave e um segredo também foram retornados.

A chave e o segredo retornados se tornarão, como mostrado na tabela acima, o Jitterbit-Connector-Key e Jitterbit-Connector-Secret no manifesto para o contêiner.

O conector recebeu um ID de ponto de extremidade e uma faixa de IDs de ponto de extremidade de atividade (função), do primeiro ao último. No caso do conector do Dropbox, que possui quatro atividades (Fetch File, Get File, Process File e Put File), você deve atribuir IDs individuais a cada atividade de forma que elas se enquadrem na faixa atribuída. Um máximo de 99 atividades pode ser atribuído a um conector individual.

Conectores podem ser registrados em qualquer ponto do processo de desenvolvimento (seja enquanto você está formulando seu design ou logo antes de empacotar). No entanto, é uma boa prática fazer isso o mais cedo possível, caso haja algum problema no seu registro ou na obtenção das chaves necessárias.

Lista de conectores registrados

Use este método para ver todos os conectores atualmente registrados em uma organização. Ele utiliza as variáveis host e orgId do ambiente Postman.

Dentro do Postman, execute essas duas APIs na ordem:

1. Log In User (necessário apenas se você ainda não o executou na sessão atual; veja Registrando um conector)

2. List Registered Connectors

   Esta captura de tela mostra a lista de conectores registrados retornada para a organização atual:

   

Excluir um conector registrado

Se necessário, você pode excluir um conector registrado. Para excluir um conector, é necessário ter tanto a organização (orgId) a que ele pertence quanto o ID do conector (connectorId). O ID do conector foi exibido quando o conector foi registrado e pode ser encontrado usando o método Lista de conectores registrados para ver todos os conectores atualmente registrados em uma organização.

Dentro do Postman, execute essas duas APIs na ordem:

1. Log In User (necessário apenas se você ainda não o executou na sessão atual; veja Registrando um conector)

2. Delete a Registered Connector

   Esta captura de tela mostra a mensagem retornada se o conector especificado pelo connectorId foi excluído com sucesso:

   

Validar uma chave/secreto de conector

Você pode validar o nome, a chave e o segredo de um conector registrado. Insira os valores nas variáveis de ambiente connectorName, key e secret do Postman e, em seguida, use esta API. Observe que todos os três itens são necessários, incluindo o nome do conector, para validar a chave e o segredo do conector.

Esses valores foram exibidos quando o conector foi registrado e podem ser encontrados usando o método Listar conectores registrados para ver todos os conectores atualmente registrados em uma organização.

A partir do Postman, execute essas duas APIs na ordem:

1. Log In User (necessário apenas se você ainda não o executou na sessão atual; veja Registrando um Conector)

2. Validate Connector Key/Secret

   Esta captura de tela mostra a mensagem retornada se o conector especificado pelo connectorId foi validado com sucesso (a chave e o segredo estão corretos para o conector nomeado):

   

Manifesto do Conector

Como parte da construção do Maven, esses atributos devem estar presentes como parte do MANIFEST.MF para indicar que é um conector Harmony. Usando o manifesto do conector Dropbox, com suas atividades—Buscar Arquivo, Colocar Arquivo, Processar Arquivo e Obter Arquivo—e os valores para endpointEntityId, functionEntityStartID e functionEntityEndID como mostrado acima, você poderia construir um manifesto 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

Neste exemplo da seção anterior, o ID do endpoint do conector era 20101, o ID da atividade inicial era 20102 e o ID da atividade final era 20200. A atividade Fetch File pode então ser atribuída a 20102, a atividade Put File pode ser atribuída a 20103, a atividade Process File pode ser atribuída a 20104, e a atividade Get File pode ser atribuída a 20105. Atividades adicionais podem, se necessário, ser registradas e atribuídas IDs, desde que estejam dentro da faixa alocada.

Mudar um conector registrado

Se você fizer alterações em um conector registrado, e especialmente em um que foi implantado em produção, esteja ciente de como as mudanças podem e irão afetar projetos existentes que utilizam esse conector.

Quando um conector é implantado no Harmony, os IDs especificados no arquivo MANIFEST.MF são revisados para garantir que todas as instâncias do conector em diferentes regiões sejam consistentes.

Em geral, siga estas práticas para atribuir atividades no MANIFEST.MF:

• Sempre atribua as atividades em ordem e incremente cada atividade em 1. Não deixe lacunas.
• Se você souber que irá adicionar uma atividade mais tarde, é melhor adicioná-la mais cedo e criar um stub para ela nos arquivos Java como no-ops. Esses podem ser preenchidos quando estiverem prontos.
• Atividades podem ser ocultadas ao não incluí-las no arquivo adapter.json.
• Uma vez atribuídas e implantadas, não mude a ordem das atividades conforme listadas no MANIFEST.MF.
• Adicione quaisquer novas atividades após a última atividade, na próxima posição disponível.
• Não exclua uma atividade existente do MANIFEST.MF. Em vez disso, remova a atividade do adapter.json e crie um stub para seu código nos arquivos Java como no-ops.

Excluir uma atividade existente que está no meio de uma lista de atividades pode resultar na mudança dos IDs das outras atividades e uma atividade Update se tornando uma atividade Create em projetos existentes.