Tutorial do conector Dropbox

Introdução

Este tutorial aborda o conector Dropbox, um conector completo criado com o Jitterbit Connector SDK. Embora esteja totalmente funcional, este conector não se destina ao uso em produção. Ele se destina a ser um ponto de partida para o desenvolvimento do conector, pois não possui todos os testes e tratamento de erros que seriam esperados em um conector de produção.

Desde que você tenha atendido aos pré-requisitos, você pode baixe o exemplo, crie e empacote-o, instale-o em um agente privado Jitterbit e use-o em um projeto para conectar ao Dropbox e mover arquivos.

O tutorial pressupõe que você esteja familiarizado com o Jitterbit e o Jitterbit Integration Studio. Se você não estiver familiarizado com o Integration Studio, revise nosso Integration Studio documentação, em particular a Guia de início rápido do Integration Studio.

Obtenha o conector Dropbox de exemplo

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

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

Registre seu conector Dropbox de exemplo

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

Caixa de depósito

O primeiro passo é no próprio Dropbox. Como o conector será um aplicativo que faz interface com o Dropbox, você precisa se registrar no Dropbox como desenvolvedor e criar um aplicativo 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, criar 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 (destacada em vermelho) onde eles podem ser obtidos na página da web:

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

Clique no botão Gerar para gerar o token de acesso, copie a chave do aplicativo e o token de acesso e armazene-os com segurança 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 todos os arquivos que você colocar ou buscar com o conector serão originados.

Harmony

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

Registro do conector Jitterbit

Todos os conectores Jitterbit exigem registro, o que envolve o uso de uma API Jitterbit para registrar o conector usando suas credenciais 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 de postman/jitterbit-env-variable-postman.json no Postman e associá-los à coleção.

Edite o ambiente e insira o hospedar (conforme definido pela sua região; consulte Encontre minha região), email (seu-nome-de-usuário-jitterbit-harmony@exemplo.com), senha (sua senha do Harmony ) e nome do conector variáveis de ambiente apropriadamente:

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

Agora, no Postman, execute essas duas APIs em ordem:

1. Log In User
2. Register a Connector

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

A resposta retornada pelo Register Connector A API contém os valores-chave necessários para o conector manifest para concluir 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, tem um ID de entidade de endpoint de 20101, e pode ter IDs de entidade de atividade de função variando de 20102 para 20200.

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

O conector recebeu uma ID de endpoint e uma gama de IDs de endpoint de atividade (função), do primeiro ao o último. No caso do conector Dropbox, que tem quatro atividades (Buscar arquivo, Obter arquivo, Processar arquivo e Coloque o arquivo), você atribuiria IDs individuais a cada atividade de modo que elas caíssem dentro do intervalo atribuído. Um no máximo 99 atividades podem ser atribuídas a um conector individual.

Complete o arquivo manifesto

Com as informações obtidas, agora você pode definir os valores no arquivo manifesto MANIFEST.MF localizado no conector Dropbox clonado Repositório GitHub em

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 tem quatro atividades, você pode usar o ID inicial para Jitterbit-Activity-EntityTypeId-fetch(a atividade Fetch File) e então incremente os IDs para as outras três atividades. A última atividade deve ser menor ou igual a 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 manifesto.

Crie o conector do Dropbox

Depois de editar e salvar as entradas do manifesto, você está pronto para construir o conector. Execute esses comandos dentro do dropbox-connector diretório 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

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

Isso compilará, testará, construirá, empacotará e instalará o conector. O arquivo JAR completo 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 obter detalhes sobre a instalação de agentes, consulte 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, ele 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 como --volume "$(pwd)/dropbox-connector:/opt/jitterbit/Connectors"

Se você estiver usando a imagem do agente privado Harmony Docker, isto permite que você monte um diretório hospedar em um diretório de contêiner, como /connectors. Dentro do contêiner Docker, o agente fará a varredura do /opt/jitterbit/Connectors diretório para arquivos JAR que contêm uma implementação de conector (apenas uma implementação de conector é permitida em cada arquivo JAR). Para implantar o JAR do conector Dropbox depois que ele tiver foi construído, ao executar o agente como um contêiner Docker, copie o arquivo JAR do build target diretório para o diretório montado como o diretório de conectores e reinicie o contêiner. Quando o contêiner Docker inicia, ele copia o conteúdo do diretório montado para o /opt/jitterbit/Connectors diretório.

Em todos os casos, não use o diretório de build 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 build do Maven. Em vez disso, copie o JAR concluído para o diretório de conectores quando o processo de build for concluído. Isso pode ser executado manualmente ou incorporado como uma etapa após uma build bem-sucedida.

O agente verifica continuamente o diretório de conectores em busca de alterações e recarrega automaticamente todos os JARs de conectores que ele encontrar que sejam novos ou tenham sido modificados. Isso significa que, conforme você desenvolve seu conector, basta copiar cada novo build para o diretório de conectores para que ele seja recarregado automaticamente pelo agente.

Exemplo Docker

Por exemplo, em um sistema Linux executando um agente privado Docker, executar este comando no diretório pai do

dropbox-connector iniciará um agente Docker com o target diretório mapeado para o /opt/jitterbit/Connectors diretório 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 ficaria assim; 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 sistema operacional Windows ), 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

Em um prompt de comando diferente (ou PowerShell, para sistema operacional Windows ), 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 /opt/jitterbit/bin/jitterbit utilitário. Para uma mensagem de ajuda, de dentro do contêiner use:

/opt/jitterbit/bin/jitterbit help

De dentro do contêiner, siga 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-tópico-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-tópico-1] `org.jitterbit.connector.sdk.BaseJitterbitConnector.onInit onInit() connector name: Dropbox
. . .

Se você vir mensagens semelhantes a estas nos logs, significa que o conector Dropbox foi conectado com sucesso. carregado e iniciado. Agora você pode fazer login no Portal da Harmony e acesso Integration Studio para começar a usar o conector.

Em um projeto dentro do ambiente ao qual o agente privado está associado, você deverá ver o conector Dropbox na paleta de componentes de design. Você pode então configurar o endpoint como faria usando qualquer outro conector no Cloud Estúdio.

Use o conector Dropbox

Agora você deve ver o conector em projetos que usam o ambiente associado ao seu agente privado e o conector. Ele deve aparecer no paleta de componentes de design aba Conectividade quando o menu suspenso Mostrar está definido para filtrar por Conectores ou Todos:

Caso contrário, consulte a seção de solução de problemas no final deste documento para sugestões antes de prosseguir.

Configurar uma conexão Dropbox

A primeira tarefa é usar o conector Dropbox para configurar uma conexão Dropbox para estabelecer conectividade com o endpoint. Na paleta de componentes, certifique-se de que o menu suspenso Mostrar esteja definido para filtrar em Conectores ou Todos, clique no conector Dropbox para abrir a configuração da conexão. Dê um nome à conexão (como como "Dropbox") e insira a Chave do aplicativo Dropbox e o Token de acesso 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 salve a configuração e retorne ao workflow.

Agora você deve ver quatro atividades na conexão configurada do Dropbox na paleta de componentes: Processar arquivo, Buscar arquivo, obter arquivo e colocar arquivo. Essas atividades agora podem ser adicionadas às operações na quadro de design e configurados como fontes ou alvos em uma operação. Juntos, uma conexão específica e suas atividades são referidas como um endpoint:

Cenários de tutoriais

Cada um desses cenários de tutorial demonstra uma atividade diferente do conector:

• Cenário 1: Buscar arquivo: Obtenha um arquivo de texto do Dropbox e grave-o como um arquivo XML em um servidor FTP.
• Cenário 2: Obter arquivo: Obtenha um arquivo de texto do Dropbox e grave-o como um arquivo de texto em um servidor FTP.
• Cenário 3: Colocar arquivo: Leia um arquivo de texto de um servidor FTP e coloque-o no Dropbox como um arquivo de texto.
• Cenário 4: Arquivo de Processo: Obtenha um arquivo XML do Dropbox, processe-o e grave-o como um arquivo JSON em um servidor FTP.
• Cenário 5: Obter arquivo: Obtenha um arquivo do Dropbox e grave-o em um servidor FTP.

Para concluir os cenários do tutorial, você precisará de credenciais (hospedar, nome de usuário e senha) para um servidor FTP. Se você concluiu recentemente o treinamento da Jitterbit University e tem credenciais válidas, você pode usar o servidor FTP desse curso. Configurar um endpoint FTP, inserindo o hospedar, 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 no Solução de problemas do Connector SDK página.