Registro do Conector¶

Introdução¶

Todos os conectores usados no Harmony devem ser registrados e os desenvolvedores que usam o Harmony O SDK do conector precisa registrar seus conectores antes de criá-los e empacotá-los.

Cada conector e cada uma de suas atividades recebe um ID exclusivo do Jitterbit que o identifica de todos os outros conectores e suas atividades.

Antes de criar um arquivo JAR de conector, você precisará obter do Harmony estes valores para cada conector:

• ID do conector
• Chave conectora
• Segredo do conector
• ID da entidade do Endpoint
• ID da atividade inicial
• ID da atividade final

API REST para registrar conectores¶

Para obter esses valores, use o Jitterbit Connector Manager API, disponível como uma coleção Postman incluída no Conector do Dropbox no postman/JitterbitConnectorManagerAPI.collection.json.

A coleção fornece estas funções (“solicitações”):

• Entrar usuário
• Registrar um conector
• Listar Conectores Registrados
• Excluir um conector de registro
• Validar chave/segredo do conector

Configurando a API no Postman¶

Antes de executar a API REST, importe as variáveis de ambiente de

postman/JitterbitConnectorManagerAPIEnvVariables.json no Postman e associá-los à coleção.

Edite o ambiente Postman e insira valores para as chaves host (conforme definido pela sua região; consulte Encontrando minha região), email (seu Harmony nome de usuário), password (sua senha do Harmony ), Harmony orgID, e o conector name, version, e description. As outras variáveis de ambiente (authToken, connectorID, key, e secret) será inserido por Postman conforme você usa as APIs:

O nome sob o qual o conector está registrado deve corresponder ao valor no adapter.json arquivo usado para descrever a interface do usuário. (Para obter detalhes sobre a IU do Cloud Studio e o adapter.json arquivo, consulte Implementação do conector e Componentes de IU do SDK do conector.)

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

Registrando um conector¶

Para registrar um conector, execute estas duas APIs em ordem com o Postman:

1. Log In User

   

2. Register a Connector

   

A resposta devolvida pelo Register a 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": "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, tem um ID de entidade de endpoint de 20101, e podem ter IDs de entidade de atividade de função variando de 20102 através 20200. Uma chave e um segredo tem também foi devolvido.

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

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.

Os conectores podem ser registrados em qualquer ponto do processo de desenvolvimento (enquanto você está formulando seu design ou imediatamente antes da embalagem). No entanto, é uma boa prática fazer isso o mais rápido possível, caso haja alguma problemas em seu registro ou na obtenção das chaves necessárias.

Listando conectores registrados¶

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

De dentro do Postman, execute estas duas APIs em ordem:

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

2. List Registered Connectors

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

   

Excluindo um conector registrado¶

Se necessário, você pode excluir um conector registrado. Excluir um conector requer que você tenha a organização (orgId) ao qual pertence e o ID do conector (connectorId). A ID do conector foi exibida quando o conector foi registrado e pode ser encontrado usando List Registered Connectors método para ver todos os conectores atualmente registrados em uma organização.

De dentro do Postman, execute estas duas APIs em ordem:

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

2. Delete a Registered Connector

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

   

Validando uma chave/segredo do conector¶

Você pode validar o nome, a chave e o segredo de um conector registrado. Insira os valores no connectorName, key, e secret Variáveis de ambiente Postman e, em seguida, use esta API. Observe que todos os três itens são obrigató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 Listar conectores registrados para ver todos os conectores atualmente registrados em uma organização.

De dentro do Postman, execute estas duas APIs em ordem:

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

2. Validate Connector Key/Secret

   Esta captura de tela mostra a mensagem retornada se o conector especificado pelo connectorId foi com sucesso validado (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 do Dropbox, com suas atividades—Fetch File, Put File, Process File e Get File — 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 foi 20101, o ID da atividade inicial era 20102, e o ID da atividade final era 20200. A atividade Buscar arquivo pode então ser atribuída 20102, o Arquivo Colocar atividade pode ser atribuída 20103, a atividade Processar arquivo pode ser atribuída 20104, e a atividade Get File pode ser atribuído 20105. Atividades adicionais podem, se necessário, ser registradas e identificadas, desde que se enquadrem dentro do intervalo alocado.

Alterando um conector registrado¶

Se você fizer alterações em um conector registrado e especialmente em um que foi implantado na produção, saiba como as alterações podem e afetarão os projetos existentes que usam esse conector.

Quando um conector é implantado no Harmony, os IDs especificados no MANIFEST.MF arquivo 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ê sabe que adicionará uma atividade mais tarde, é melhor adicioná-la antes e eliminar o código dela nos arquivos Java como não operacional. Estes podem ser preenchidos quando estiverem prontos.
• As atividades podem ser ocultadas ao não incluí-las no adapter.json arquivo.
• Uma vez atribuído e implantado, não altere a ordem das atividades listadas no MANIFEST.MF.
• Adicionar 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 de adapter.json, e elimine seu código nos arquivos Java para ser não operacional.

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