Tutorial do conector Dropbox para o Jitterbit Connector SDK

Introdução

Este tutorial aborda o conector Dropbox, um conector completo construído com o Jitterbit Connector SDK. Embora esteja totalmente funcional, este conector não é destinado ao uso em produção. Ele serve como um ponto de partida para o desenvolvimento de conectores, pois não possui todos os testes e o tratamento de erros que seriam esperados em um conector de produção.

Desde que você tenha atendido aos pré-requisitos, você pode baixar o exemplo, compilar e empacotá-lo, instalá-lo em um agente privado do Jitterbit e usá-lo em um projeto para se conectar ao Dropbox e mover arquivos.

O tutorial assume que você está familiarizado tanto com o Jitterbit quanto com o Jitterbit Integration Studio. Se você não estiver familiarizado com o Integration Studio, por favor, revise nossa documentação do Integration Studio, em particular o guia de início rápido do Integration Studio.

Obter o exemplo do conector Dropbox

Se você ainda não fez isso, o primeiro passo é clonar o conector Dropbox do repositório do GitHub. Você pode fazer isso pelo site do GitHub ou executando os seguintes comandos:

git clone https://github.com/jitterbit/dropbox-connector.git
cd dropbox-connector

Registrar seu exemplo de conector Dropbox

Você precisará de certas informações antes de poder compilar e empacotar o conector: um login e aplicativo do Dropbox, um nome de usuário e senha da conta Harmony, e valores da registro do conector Jitterbit. Os valores obtidos do registro do conector são usados no manifesto antes de compilar e empacotar o conector.

Dropbox

O primeiro passo é no próprio Dropbox. Como o conector será um aplicativo que interage com o Dropbox, você precisará se registrar no Dropbox como desenvolvedor e criar um aplicativo do Dropbox usando a API do Dropbox. O aplicativo pode ter qualquer nome e configurações. Isso pode ser feito com uma conta gratuita do Dropbox. No site do Dropbox, crie um aplicativo:

Na página da web do seu novo aplicativo, obtenha sua chave de aplicativo e gere um token de acesso. Esta imagem mostra (destacado em vermelho) onde esses dados podem ser obtidos na página da web:

Neste exemplo, um aplicativo chamado "Teste do Jitterbit Connector SDK" foi criado. A chave do aplicativo é exibida como "xxxxxxxxxxxxxxx". O token de acesso será exibido assim que o botão Gerar abaixo do rótulo Token de acesso gerado for utilizado.

Clique no botão Gerar para gerar o token de acesso, copie tanto a chave do aplicativo quanto o token de acesso e armazene-os em um local seguro onde você possa recuperá-los ao configurar o conector.

Observe a configuração do Nome da pasta do aplicativo (destacado em azul). Neste exemplo, esta é a pasta raiz no Dropbox de onde quaisquer arquivos que você colocar ou buscar com o conector se originarão.

Harmony

Se você ainda não obteve um nome de usuário e senha do Harmony, precisará de um antes de prosseguir. (Uma licença de teste é suficiente: vá para https://jitterbit.com e clique no botão Solicitar Teste para se inscrever.)

Registro do conector Jitterbit

Todos os conectores Jitterbit requerem registro, que envolve o uso de uma API Jitterbit para registrar o conector usando suas credenciais do Harmony.

Para registrar o conector e obter os valores de registro, use a coleção Postman incluída no conector Dropbox como postman/JitterbitConnectorManagerAPI.collection.json.

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

Edite o ambiente e insira o host (conforme definido pela sua região; veja Encontre minha região), email (seu-nome-de-usuario-harmony-jitterbit@example.com), senha (sua senha do Harmony) e nome do conector as variáveis de ambiente apropriadas:

O nome sob o qual o conector está registrado deve corresponder ao valor no arquivo adapter.json usado para descrever a UI. Para este tutorial, o name do conector fornecido no arquivo adapter.json do Dropbox é Dropbox. Para detalhes sobre o arquivo da UI, consulte Implementação do conector e Componentes da UI do SDK do Conector.

Agora, a partir do Postman, execute estas duas APIs na ordem:

Log In User
Register a Connector

(As outras APIs na coleção podem ser usadas para listar e excluir conectores existentes que você registrou anteriormente, e para confirmar a validade da chave e do segredo de um conector.)

A resposta retornada pela API Register Connector contém as chaves-valor necessárias para que o manifesto do conector complete o registro do conector. Você deve receber uma resposta como:

{
  "status": true,
  "operation": "Register a connector",
  "id": "3691",
  "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "secret": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "endpointEntityId": "20101",
  "functionEntityStartId": "20102",
  "functionEntityEndId": "20200"
}

Como pode ser visto neste exemplo, um conector foi registrado, possui um ID de entidade de endpoint de 20101, e pode ter IDs de entidades de atividade de função variando de 20102 a 20200.

API de Registro do Conector	Chaves do Arquivo Manifesto
`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>`

A chave e o segredo retornados se tornarão, conforme a tabela acima, o Jitterbit-Connector-Key e Jitterbit-Connector-Secret no manifesto do conector.

O conector recebeu um ID de endpoint e uma faixa de IDs de endpoint de atividade (função), do primeiro ao último. No caso do conector do Dropbox, que possui quatro atividades (Buscar Arquivo, Obter Arquivo, Processar Arquivo e Colocar Arquivo), você deve atribuir IDs individuais a cada atividade de forma que eles estejam dentro da faixa atribuída. Um máximo de 99 atividades pode ser atribuído a um conector individual.

Complete o arquivo de manifesto

Com as informações obtidas, você pode agora definir os valores no arquivo de manifesto MANIFEST.MF localizado no repositório clonado do conector do Dropbox no diretório src/main/resources/META-INF:

Author: Jitterbit
Version: 1.0.0
Jitterbit-Connector-Key: <key>
Jitterbit-Connector-Secret: <secret>
Jitterbit-Connector-Endpoint-EntityTypeId: <endpoint_type_id>
Jitterbit-Activity-EntityTypeId-fetch: <id-1>
Jitterbit-Activity-EntityTypeId-put: <id-2>
Jitterbit-Activity-EntityTypeId-process: <id-3>
Jitterbit-Activity-EntityTypeId-get: <id-4>
Jitterbit-Connector-UI: adapter.json
Class-Path: lib/dropbox-core-sdk-3.0.6.jar

A chave, o segredo e os IDs foram retornados do registro do conector. Como o conector do Dropbox possui quatro atividades, você pode usar o ID inicial para Jitterbit-Activity-EntityTypeId-fetch (a atividade Buscar Arquivo) e, em seguida, incrementar os IDs para as outras três atividades. A última atividade deve ser menor ou igual ao functionEntityEndId. Complete esses valores antes de construir o conector. Observe que deve haver um espaço entre os dois pontos do rótulo e o valor em cada linha do arquivo de manifesto.

Aviso

Se você estiver construindo o conector no Windows, observe que o arquivo de manifesto deve ter uma quebra de linha/retorno de carro no final; caso contrário, a última entrada (Class-Path) será ignorada e não será incluída no arquivo de manifesto incluído no arquivo JAR de saída.

Construa o conector do Dropbox

Após editar e salvar as entradas do manifesto, você está pronto para construir o conector. Execute esses comandos dentro do diretório dropbox-connector que contém o repositório clonado com o manifesto editado:

export APP_KEY=<dropbox-app-key>
export ACCESS_TOKEN=<dropbox-access-token>
mvn jaxb2:xjc compile install

Nota

Se a variável de ambiente JAVA_HOME não estiver configurada para o Java SE Development Kit 8, você pode configurá-la temporariamente para uma única construção do Maven com o seguinte comando:

JAVA_HOME="/Path/to/JDK/jdk-1.8.jdk/Contents/Home" mvn jaxb2:xjc compile install

Isso irá compilar, testar, construir, empacotar e instalar o conector. O arquivo JAR concluído estará em:

dropbox-connector/target/jitterbit-connector-dropbox-1.0.0.jar

Instalar o conector

O conector concluído agora pode ser instalado em um agente privado. (Para detalhes sobre a instalação de agentes, veja Requisitos do sistema para agentes privados).

Para que o agente encontre o conector, o JAR do conector precisa ser colocado no diretório de conectores do agente. Normalmente, isso está localizado em:

Linux: /opt/jitterbit/Connectors
Windows: C:\Program Files (x86)\Jitterbit Agent\Connectors (privilégios de administrador necessários)
Docker: o diretório mapeado para /opt/jitterbit/Connectors no comando Docker, como --volume "$(pwd)/dropbox-connector:/opt/jitterbit/Connectors"

Se você estiver usando a imagem do agente privado Docker Harmony, ela permite que você monte um diretório do host em um diretório do contêiner, como /connectors. Dentro do contêiner Docker, o agente irá escanear o diretório /opt/jitterbit/Connectors em busca de arquivos JAR que contenham uma implementação de conector (é permitida apenas uma implementação de conector em cada arquivo JAR). Para implantar o JAR do conector Dropbox após ele ter sido construído, enquanto executa o agente como um contêiner Docker, copie o arquivo JAR do diretório target de construção para o diretório montado como o diretório de conectores e reinicie o contêiner. Quando o contêiner Docker iniciar, ele copia o conteúdo do diretório montado para o diretório /opt/jitterbit/Connectors.

Em todos os casos, não use o diretório de construção do Maven como o diretório de conectores, pois a varredura do diretório ficará confusa ao encontrar os estágios intermediários do processo de construção do Maven. Em vez disso, copie o JAR concluído para o diretório de conectores quando o processo de construção estiver finalizado. Isso pode ser realizado manualmente ou incorporado como uma etapa após uma construção bem-sucedida.

O agente verifica continuamente o diretório de conectores em busca de alterações e recarrega automaticamente quaisquer JARs de conectores que encontrar que sejam novos ou tenham sido modificados. Isso significa que, à medida que você desenvolve seu conector, basta copiar cada nova versão para o diretório de conectores para que ela seja recarregada automaticamente pelo agente.

Exemplo de Docker

Por exemplo, em um sistema Linux executando um agente privado do Docker, executar este comando no diretório pai do dropbox-connector iniciará um agente Docker com o diretório target mapeado para o diretório /opt/jitterbit/Connectors do agente:

docker run --interactive --tty --name=jitterbit-agent --publish 3000:3000 \
           --volume "$(pwd)/dropbox-connector/target:/opt/jitterbit/Connectors" \
           --env-file "$(pwd)/private-agent.env" \
           jitterbit/agent

onde private-agent.env contém as variáveis de ambiente usadas para conectar ao Harmony.

O arquivo private-agent.env teria a seguinte aparência; substitua os valores apropriados:

HARMONY_USERNAME="<email_address>"
HARMONY_PASSWORD="<password>"
HARMONY_ORG="<your_organization_name>"
HARMONY_AGENT_GROUP="<your_agent_group_name>"
HARMONY_AGENT="<your_agent_name>"

Em um prompt de comando diferente (ou PowerShell, para Windows OS), você pode verificar se o contêiner Docker está ativo usando:

docker ps -a

CONTAINER ID IMAGE                  COMMAND                CREATED       STATUS       PORTS                                              NAMES
xxxxxxxxxxxx jitterbit/agent:latest "/entrypoint.sh /ag…" 2 minutes ago Up 2 minutes 46908-46909/tcp, 0.0.0.0:3000->3000/tcp, 46912/tcp jitterbit-agent

Nota

Uma vez que o contêiner esteja ativo e passe na verificação de saúde, você pode fazer login no portal Harmony e ir para a página Console de Gerenciamento Agentes para verificar se o agente foi registrado e está em execução.

Em um prompt de comando diferente (ou PowerShell, para Windows OS), você pode acessar o contêiner usando um comando para abrir um shell no contêiner Docker:

docker exec -ti jitterbit-agent /bin/bash

root@b3160de34840:/opt/jitterbit#

Neste ponto, você tem acesso total ao contêiner do agente. Você pode parar e reiniciar o agente usando o utilitário /opt/jitterbit/bin/jitterbit. Para uma mensagem de ajuda, de dentro do contêiner, use:

/opt/jitterbit/bin/jitterbit help

De dentro do contêiner, monitore os logs do Tomcat para verificar os logs do conector:

tail -f tomcat/logs/catalina.out

. . .
2018-04-26 13:28:48,957 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorLoader:63 - Loading connectors...
. . .
2018-04-26 13:28:49,185 WARN com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:96 - Could not load Jitterbit Connector via manifest.mf; no Main-Class or Jitterbit-Connector-Factory-Class attributes defined.
2018-04-26 13:28:49,186 WARN com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:97 - Falling back to annotation system
2018-04-26 13:28:49,187 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:440 - Temporary Directory for undeploying connectors bundle: /opt/jitterbit/tomcat/temp
2018-04-26 13:28:49,517 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:377 - Loading annotated class java.lang.Class
2018-04-26 13:28:49,527 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:395 - Register Activity Factory with id: 200500 name: put factory: org.jitterbit.connector.dropbox.activities.PutFileActivity$PutFileActivityFactory
2018-04-26 13:28:49,530 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:395 - Register Activity Factory with id: 200402 name: fetch factory: org.jitterbit.connector.dropbox.activities.FetchFileActivity$FetchFileActivityFactory
. . .
26-Apr-2018 13:29:22.615 INFO [pool-1-thread-1] org.jitterbit.connector.ConnectorRegistry.registerConnector Connector Name: Dropbox Author: Jitterbit Connector Key: 929f90...52562 Endpoint Entity Type Id: 200401 Internal Connector: false Activities Id: {fetch=200402, put=200500}
26-Apr-2018 13:29:22.617 INFO [pool-1-thread-1] org.jitterbit.connector.sdk.BaseJitterbitConnector.onInit onInit() connector name: Dropbox
. . .

Se você ver mensagens semelhantes a estas nos logs, isso significa que o conector do Dropbox foi carregado e iniciado com sucesso. Agora você pode fazer login no portal Harmony e acessar Integration Studio para começar a usar o conector.

Em um projeto dentro do ambiente associado ao agente privado, você deve ver o conector do Dropbox na paleta de componentes de design. Você pode então configurar o endpoint como faria com qualquer outro conector no Cloud Studio.

Usar o conector do Dropbox

Agora você deve ver o conector em projetos que utilizam o ambiente associado ao seu agente privado e ao conector. Ele deve aparecer na aba Conectividade da paleta de componentes de design quando o dropdown Mostrar estiver configurado para filtrar por Conectores ou Todos:

Se não, consulte a seção de solução de problemas no final deste documento para sugestões antes de prosseguir.

Configurar uma conexão do Dropbox

A primeira tarefa é usar o conector do Dropbox para configurar uma conexão do Dropbox para estabelecer conectividade com o endpoint. Na paleta de componentes, certificando-se de que o dropdown Mostrar esteja configurado para filtrar por Conectores ou Todos, clique no conector do Dropbox para abrir a configuração da conexão. Dê um nome à conexão (como "Dropbox") e insira a Chave do App do Dropbox e o Token de Acesso do Dropbox que você salvou anteriormente:

Clique no botão Testar para confirmar que a conexão foi bem-sucedida e, em seguida, clique no botão Salvar Alterações para salvar a configuração e retornar ao fluxo de trabalho.

Agora você deve ver quatro atividades sob a conexão do Dropbox configurada na paleta de componentes: Processar Arquivo, Buscar Arquivo, Obter Arquivo e Colocar Arquivo. Essas atividades podem agora ser adicionadas a operações na tela de design e configuradas como fontes ou destinos em uma operação. Juntas, uma conexão específica e suas atividades são referidas como um endpoint:

Cenários de tutorial

Esses cenários de tutorial demonstram cada uma das diferentes atividades do conector:

Cenário 1: Buscar Arquivo: Buscar um arquivo de texto do Dropbox e gravá-lo como um arquivo XML em um servidor FTP.
Cenário 2: Buscar Arquivo: Buscar um arquivo de texto do Dropbox e gravá-lo como um arquivo de texto em um servidor FTP.
Cenário 3: Colocar Arquivo: Ler um arquivo de texto de um servidor FTP e colocá-lo no Dropbox como um arquivo de texto.
Cenário 4: Processar Arquivo: Buscar um arquivo XML do Dropbox, processá-lo e gravá-lo como um arquivo JSON em um servidor FTP.
Cenário 5: Obter Arquivo: Obter um arquivo do Dropbox e gravá-lo em um servidor FTP.

Para completar os cenários de tutorial, você precisará de credenciais (host, nome de usuário e senha) para um servidor FTP. Se você recentemente completou o treinamento da Jitterbit University e possui credenciais válidas, pode usar o servidor FTP desse curso. Configure um endpoint FTP, inserindo o host, nome de usuário e senha. Nestes tutoriais, o endpoint FTP é nomeado usando o nome "FTP":

Solução de Problemas

Se você não conseguir carregar o conector ou vê-lo no Integration Studio, confira as dicas na página de solução de problemas do SDK do Conector.