Tutorial do conector do Dropbox¶

Introdução¶

Este tutorial aborda o conector do Dropbox, um conector completo criado com o Harmony Connector SDK. Embora esteja funcionando perfeitamente, esse conector não se destina ao uso em produção. Destina-se como um ponto de partida importante para o desenvolvimento de conectores, pois não possui todos os testes e tratamento de erros que seriam esperado em um conector de produção.

Desde que você tenha cumprido os pré-requisitos, você pode baixe o exemplo, crie e empacote-o, instale-o em um Harmony Agente Privado e use-o em um projeto para se conectar ao Dropbox e mover arquivos.

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

Obtendo o exemplo de conector do Dropbox¶

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

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

Registrando seu exemplo de conector do Dropbox¶

Você precisará de algumas informações antes de 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.

Dropbox¶

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 do Dropbox usando a API do Dropbox. A aplicação 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 a chave do aplicativo e gere um token de acesso. Esta imagem mostra (descrita em vermelho) onde estes podem ser obtidos na página 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 Gerado token de acesso foi 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ê pode 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 serão originados todos os arquivos que você colocar ou buscar com o conector.

Harmony¶

Se você ainda não obteve um nome de usuário e senha do Harmony, precisará de um antes de prosseguir. (A licença de avaliação é suficiente: vá para < https://jitterbit.com > e clique no botão Solicitar avaliação 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 do Harmony.

Para registrar o conector e obter os valores de registro, use a coleção Postman incluída no Conector do 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 por sua região; consulte Encontrando minha região), e-mail (seu-jitterbit-harmony-username@example.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 o IU. Para este tutorial, o conector name fornecido no Dropbox adapter.json arquivo é Dropbox. Para detalhes sobre o arquivo de interface do usuário, consulte Implementação do conector e Componentes de IU do SDK do conector.

Agora, de dentro do Postman, execute estas 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ê já registrado e para confirmar a validade da chave e do segredo de um conector.)

A resposta devolvida 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 têm IDs de entidade de atividade de função que variam de 20102 para 20200.

A chave e o segredo devolvidos serão, conforme tabela acima, os Jitterbit-Connector-Key e Jitterbit-Connector-Secret no manifesto do conector.

O conector recebeu um ID de endpoint e um intervalo de IDs de endpoint de atividade (função), do primeiro ao o último. No caso do conector do Dropbox, que possui quatro atividades (Fetch File, Get File, Process File e Put File), você atribuiria IDs individuais a cada atividade de forma que eles estivessem dentro do intervalo designado. A máximo de 99 atividades podem ser atribuídas a um conector individual.

Completando o arquivo de manifesto¶

Com as informações obtidas, agora você pode definir os valores no arquivo de manifesto MANIFEST.MF localizado no clonado Conector do Dropbox 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 Buscar arquivo) e em seguida, incremente os IDs para as outras três atividades. A última atividade deve ser menor ou igual à functionEntityEndId. Preencha 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.

Construindo o conector do Dropbox¶

Depois de editar e salvar as entradas do manifesto, agora você está pronto para construir o conector. Execute este comando dentro do dropbox-connector diretório que contém o repositório clonado com o manifesto editado:

$ mvn jaxb2:xjc compile install

Isso compilará, testará, compilará, empacotará e instalará o conector. O arquivo JAR completo estará em:

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

Instalando 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 localize 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 (requer privilégios de administrador)
• 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 de Agente Privado do Harmony Docker, isto permite que você monte um diretório de hospedar em um diretório de contêiner, como /connectors. Dentro do contêiner do Docker, o agente irá escanear o /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 do Dropbox depois de ter foi criado, enquanto executa o agente como um contêiner do Docker, copie o arquivo JAR da compilação target diretório para o diretório montado como o diretório de conectores e reinicie o contêiner. Quando o contêiner do Docker é iniciado, 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 construção do Maven como o diretório de conectores, pois a verificação do O diretório ficará confuso ao se deparar com 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 for concluído. Isso pode ser executado manualmente ou incorporado como uma etapa após uma construção bem-sucedida.

O agente varre continuamente o diretório de conectores em busca de alterações e recarrega automaticamente todos os JARs do conector que encontra que são novos ou foram modificados. Isso significa que conforme você desenvolve seu conector, simplesmente copie cada novo construa no diretório de conectores para que ele seja recarregado automaticamente pelo agente.

Exemplo usando o Docker¶

Por exemplo, em um sistema Linux executando um Docker Agente Privado, executando este comando no diretório pai do

dropbox-connector iniciará um agente do 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 do 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 do 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-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ê vir mensagens semelhantes a essas nos logs, isso significa que o conector do Dropbox foi instalado com sucesso carregado e iniciado. Agora você pode fazer login no Portal Harmony e acesso Cloud Studio para começar a usar o conector.

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

Usando o conector do Dropbox¶

Agora você deve ver o conector em projetos que usam o ambiente associado ao seu Agente Privado e o conector. Deve aparecer no paleta de componentes de design aba Conectividade quando o menu suspenso Mostrar estiver definido para filtrar Conectores ou Todos:

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

Configurando 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, certifique-se de que o menu suspenso Mostrar esteja definido para filtrar em Conectores ou Todos, clique no conector do Dropbox para abrir a configuração da conexão. Dê um nome à conexão (como como “Dropbox”) e digite a Dropbox App Key e o Dropbox Access Token que você salvou anteriormente:

Clique no botão Testar para confirmar se 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 origens ou destinos em uma operação. Juntos, uma conexão específica e suas atividades são referidas como endpoint:

Cenários 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 FTP servidor.
• Cenário 2: Buscar Arquivo: Obtenha um arquivo de texto do Dropbox e grave-o como um arquivo de texto em um FTP servidor.
• Cenário 3: Colocar arquivo: Ler um arquivo de texto de um servidor FTP e colocá-lo no Dropbox como um texto arquivo.
• Cenário 4: Processar Arquivo: Obtenha um arquivo XML do Dropbox, processe-o e grave-o como um Arquivo JSON para 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 de 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 Cloud Studio, confira as dicas no Solução de problemas do SDK do conector página.