Ir para o conteúdo

Instalar um gateway de API privado Jitterbit no Linux

Visão geral

Estas são as instruções para instalar e configurar um gateway de API privado.

Nota

O gateway de API privado era conhecido anteriormente como gateway de API local do Jitterbit.

Pré-requisitos

Para instalar um gateway de API privado, o hardware e o software devem atender a estes requisitos:

  • Servidor Linux executando um sistema operacional de 64 bits usando uma destas distribuições:

    • Ubuntu 20.04 LTS
    • Red Hat Enterprise Linux 8
    • Red Hat Enterprise Linux 9 (verificado com versões de gateway 11.37 e posteriores)
    • Amazon Linux AMI 2

    Nota

    Pode ser possível usar outras distribuições Linux, mas elas não são suportadas atualmente pelo Jitterbit. Como cada distribuição do Linux pode variar, as instruções para instalar o gateway de API privado em outras distribuições Linux podem ser diferentes das descritas nesta página.

  • Estes são os requisitos mínimos de hardware e máquinas virtuais para um gateway de API privado:

    • Processador quad-core

    • 8 GB de RAM

    • 50 GB de espaço disponível no disco rígido

    • Taxa de transferência de 50 megabytes/segundo no disco rígido

    • Conexão de Internet de alta velocidade

    Cuidado

    A velocidade e o espaço do disco rígido são componentes essenciais do gateway de API privado, pois as cargas de solicitação e resposta são armazenadas no servidor durante as transações de API.

  • Configuração ideal do sistema e do ambiente geral executando o gateway de API privado.

    Aviso

    Se não for configurado de forma otimizada, problemas esporádicos e imprevisíveis podem resultar de problemas de rede, E/S de disco ruim, problemas de memória limitada ou insuficiente, espaço em disco limitado ou insuficiente, falhas de energia ou reinicializações abruptas do sistema.

  • Um subdomínio ou nome de domínio, apontado para o servidor (por exemplo, mysubdomain.example.com).

  • Um certificado SSL válido para o subdomínio, de uma autoridade de certificação reconhecida:

    • Não use um certificado autoassinado.
    • O certificado deve consistir em dois arquivos: um arquivo CRT (.crt) para o certificado assinado e a CHAVE (.key) para a chave privada.
    • Esses arquivos de certificado devem estar no formato PEM que um servidor NGINX pode entender.
    • Às vezes, a extensão dos arquivos é diferente; frequentemente, as extensões CRT, PEM e CER são intercambiáveis.
    • Também é possível que os dois arquivos sejam combinados em um único arquivo PFX; nesse caso, use o OpenSSL para extrair os dois arquivos.
    • Lembre-se de monitorar as datas de expiração do certificado!
    • Entre em contato com seu provedor de certificado para obter informações adicionais.
    • Certificados SSL gratuitos estão disponíveis em provedores como Let's Encrypt.

  • A partir da versão 10.3 do Harmony, por padrão, o gateway de API privado não oferece mais suporte ao Transport Layer Security (TLS) 1.0 (consulte Atualização de compatibilidade da versão TLS). Para alterar essa configuração padrão, entre em contato com suporte Jitterbit.

  • Para usar uma configuração de proxy, é necessário o gateway de API privado versão 10.30.1 ou posterior.

Instalar um gateway de API privado

Após confirmar os pré-requisitos (acima) forem atendidas, siga estas etapas para configurar um gateway de API privado:

Etapa 1: configurar a máquina do gateway da API

  1. Configure uma nova máquina Linux. É recomendado que a máquina seja dedicada para uso somente pelo gateway de API privado.

    Estas recomendações adicionais dependem do sistema operacional:

    • Red Hat Enterprise Linux (RHEL)

      Se estiver instalando o RHEL pela primeira vez nesta máquina, recomendamos usar o Compute Node com estas opções incluídas:

      • Ferramentas de depuração
      • Utilitários de monitoramento de hardware
      • Bibliotecas de compatibilidade
      • Ferramentas de desenvolvimento
      • Ferramentas de segurança

    • Ubuntu ou Debian

      Se estiver instalando o Ubuntu ou o Debian, instale com os padrões e inclua o servidor OpenSSH para que você possa efetuar login na máquina remotamente.

  2. Em muitos ambientes Linux, o firewall bloqueia automaticamente a porta HTTPS (443) necessária para o gateway de API privado.

    Para abrir a porta HTTPS, use estes comandos conforme apropriado:

    64-bit RHEL or Amazon Linux AMI
    firewall-cmd --zone=public --add-port=443/tcp --permanent
firewall-cmd --reload

    ou

    64-bit Debian or Ubuntu
    ufw allow 443/tcp

  3. Aponte o subdomínio ou domínio para o endereço IP do servidor.

  4. Confirme se você pode fazer SSH na máquina usando um cliente SSH.

Etapa 2: instalar o software de gateway de API privada

Para instalar o software de gateway de API privada, faça login na sua máquina via SSH e execute os comandos apropriados para sua versão do Linux. O link de download e o arquivo baixado variam dependendo da versão e estão nas suas informações de registro. Os arquivos de download também estão disponíveis no portal Harmony Downloads página. Ajuste os caminhos e o nome do arquivo de acordo:

Para instalar um gateway de API privado versão 10.61 ou anterior (no REHL ou Amazon Linux AMI), execute estes comandos:

64-bit RHEL or Amazon Linux AMI private API gateway version 10.61 or Earlier
sudo -i

yum update

cd ~

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x-x.x86_64.rpm

yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
Para instalar um gateway de API privado versão 10.62 ou posterior (no REHL ou Amazon Linux AMI), execute estes comandos:

64-bit RHEL or Amazon Linux AMI private API gateway version 10.62 or Later
sudo -i

yum update

cd ~

# To install required dependencies:

yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

# To download and install the private API gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x-x.x86_64.rpm

yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
Para instalar um gateway de API privado versão 10.61 ou anterior (no Debian ou Ubuntu), execute estes comandos:

64-bit Debian or Ubuntu private API gateway version 10.61 or Earlier
sudo -i

cd ~

# To install required dependencies:

apt-get update

apt-get install libzzip-dev

apt-get install libyaml-dev

apt --fix-broken install

apt install python

# To download and install the API gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x.x.amd64.deb

dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
Para instalar um gateway de API privado versão 10.62 ou posterior (no Debian ou Ubuntu), execute estes comandos:

64-bit Debian or Ubuntu private API gateway version 10.62 or Later
sudo -i

cd ~

# To install required dependencies:

apt-get update

apt-get -y install libgeoip-dev

apt --fix-broken install

ln -s /usr/bin/python2.7 /usr/bin/python

# To download and install the API gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x.x.amd64.deb

dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb

Etapa 3: instalar os arquivos do certificado SSL

O gateway de API privado requer que os arquivos de certificado para a máquina sejam nomeados nginx.crt e nginx.key e deve ser copiado para estes locais:

cp ca.crt /usr/local/openresty/nginx/ssl/nginx.crt

cp ca.key /usr/local/openresty/nginx/ssl/nginx.key

Depois de instalar os arquivos de certificado SSL, eles devem ser adicionados ao repositório de chaves Java do Jitterbit para seu agente privado. Para obter mais informações, consulte Adicionando certificados ao repositório de chaves para agentes privados.

Etapa 4: Configurar o gateway de API privado

Para concluir a instalação, execute este comando como root para configurar o gateway de API privado:

/usr/bin/jitterbit-api-gateway-config

O gateway de API privado fornece ajuda na linha de comando:

/usr/bin/jitterbit-api-gateway-config --help

# Output:

Usage: jitterbit-api-gateway-config [options]

Options:
 -h, --help            show this help message and exit
 -u USER, --user=USER  Your Harmony user name (normally your email
                       address)
 -p PASSWORD, --password=PASSWORD
                       Your Harmony password
 -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID
                       Provide your Organization Id if you have more than one
                       organization
 -e ServiceUrl, --serviceUrl=ServiceUrl
                       Your Jitterbit Services URL (e.g.
                       https://services.jitterbit.net/apis
 -s NGINX_SERVER, --server=NGINX_SERVER
                       Valid values:   start   stop   restart
 -d, --dns             interactively config dns servers
 --proxyEnabled=PROXY_ENABLED
                       Enable (true) or disable (false) a proxy
 --proxyUri=PROXY_URI  When proxy is enabled, the Uri for your proxy server.
                       e.g. http://192.168.1.100:808
 --proxyUser=PROXY_USER
                       Proxy server username
 --proxyPassword=PROXY_PASSWORD
                       Proxy server password
 -t, --test            Run self tests
 --debug               Debug output for Self Tests
 --noColor             Turn off terminal text colors

Você pode fornecer todas as informações necessárias na linha de comando ou, iniciando o comando sem nenhuma opção, entrar em uma sessão interativa que prepara o arquivo de configuração do gateway de API privado e, em seguida, oferece para iniciar o gateway. A configuração inserida é capturada no arquivo de configuração do gateway de API privado /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

Ao configurar um gateway de API privado, o nome de usuário e a senha do Harmony devem ser associados a um membro de uma papel com permissão Admin. A permissão Agent Install não é suficiente. No arquivo de configuração do gateway de API privada, os campos de nome de usuário e senha do Harmony são armazenados como criptografados, enquanto o nome de usuário e a senha do servidor proxy são armazenados como codificados em Base64. Isso é para evitar que as credenciais do proxy sejam expostas em texto não criptografado e não tem a intenção de fornecer um alto nível de segurança. Certifique-se de que o arquivo de configuração esteja armazenado de forma segura.

Na primeira vez que você configura um gateway de API privado usando credenciais do Harmony, um novo usuário de gateway de API separado com uma senha que não expira é criado automaticamente na organização como um membro da papel_Administrator_. Este usuário não está associado a um endereço de email e não pode efetuar login no portal Harmony; este usuário é apenas para fins de gateway de API. As credenciais para este usuário são adicionadas ao gatewayconfig.yaml arquivo.

Desde a versão 11.32 do gateway de API, se você reconfigurar o gateway, verá uma pergunta adicional:

Would you like to generate a new Gateway credentials and overwrite existing ones? (y/N):

Se você responder N(ou pressione Enter para a resposta padrão), as credenciais de usuário existentes são usadas. Se você responder Y, um novo usuário é criado.

Esses usuários do gateway de API são exibidos no Management Console Gerenciamento de usuários página e estão no formato de <GatewayUser>_<orgID>_<ID>. Se o mesmo usuário reconfigurar o gateway na mesma organização, o nome do usuário do gateway será anexado com um sublinhado e um número incrementado, como _1.

A saída do utilitário de configuração é semelhante à seguinte. Quando solicitado, insira as informações necessárias, como seu nome de usuário e senha do Harmony, região do Harmony, informações de proxy (se a configuração de proxy deve ser habilitada), URL de serviços (se diferente do padrão), ID da organização (se diferente do padrão para essa conta) e configuração desejada para DNS:

Jitterbit Private Gateway Configuration

Enter your Harmony user name:
Enter your Harmony password:
Are you an NA, EMEA or APAC customer (Enter one, NA, EMEA, or APAC):

Would you like to enable a proxy (Y/N)?
Enter your proxy server uri (e.g. http://192.168.1.100:808):
Enter your proxy username:
Enter your proxy password:

Connecting to Harmony...
NOTE: Default Jitterbit Services URL for NA customers is https://services.jitterbit.net/apis
NOTE: Default Jitterbit Services URL for EMEA customers is https://services.jitterbit.eu/apis
NOTE: Default Jitterbit Services URL for APAC customers is https://services.jitterbit.cc/apis

Enter Jitterbit Services URL (press enter for default):
Enter your Jitterbit Organization ID (press enter for default):
Creating Private Gateway User...

Here is the content of the DNS file that will be used for the API gateway:
The file is located here: /usr/local/openresty/nginx/conf/dnsservers.conf
resolver 127.0.1.1 valid=300s ipv6=off;

Here are the nameservers from /etc/resolve.conf:
nameserver 127.0.1.1

Would you like to use the resolv.conf DNS nameservers rather than the default nginx DNS servers? (Y/N)?

Would you like to manually add the DNS server the API gateway DNS configuration (Y/N)?
Please enter IP address or domain name. Press enter to finish:

Gateway Configuration file modified.

If you have an SSL Certificate, copy the SSL Certificate file to
    /usr/local/openresty/nginx/ssl/nginx.crt
and the SSL Certificate key file to
    /usr/local/openresty/nginx/ssl/nginx.key

Would you like the Gateway Server started? (Y/N)?
. . .

Se você responder Y para a última pergunta, o gateway de API privado deve começar a ser executado.

Se a instalação foi bem-sucedida, agora você pode acessar as APIs da organização usando o gateway de API privado. Nenhuma configuração adicional é necessária; todas as APIs na organização agora devem ser acessíveis usando o gateway de API privado.

Nota

Além de acessar as APIs da organização com suas URLs de API privadas, você ainda pode usar URLs Jitterbit. Para bloquear o acesso às URLs Jitterbit, uma operação pode primeiro confirmar que uma URL é do gateway de API privada e cancelar se não for. Aqui está um exemplo de teste na região NA (para regiões EMEA e APAC, substitua jitterbit.eu ou jitterbit.cc conforme apropriado):

<trans>
if( index($jitterbit.api.request.headers.fulluri,'jitterbit.net') >0,
    $jitterbit.api.response = 'Public API gateway not permitted';
    CancelOperationChain($jitterbit.api.response);
)
</trans>

Para assistência, entre em contato com suporte Jitterbit.

Uma inicialização bem-sucedida de gateway de API privada se parece com isso:

. . .
nginx:`[alerta] `[lua] startup.lua:0: ():
       ____  ___  __   __    ___
   | |  |   |  |__  |__) |__) |  |`FIM DA TABELA`
\__/ |  |   |  |___ |  \ |__) |  |`FIM DA TABELA`
           API gateway

Version: x.x.x.x
Build Date: 20XX/XX/XX 00:00

Loading Libraries...
Libraries loaded successfully!

Loading configuration...
Configuration file:  /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml
Configuration file successfully loaded, parsing values...

************************************************************

InfluxDB output not configured.
Loggly output not configured.
ELK output not configured.

Configuration parsing successful!

Doing startup checks...

Checks completed, no errors.

------------------------------------------------------------

Jitterbit Services URL: https://services.jitterbit.net/apis
Gateway will login as: gatewayuser
Organization ID set to: 123456

Current Time: 20XX-XX-XX 00:00:00
Gateway Startup Successful!

Gateway server started

Etapa 5: Teste o gateway de API privado

Depois que o gateway de API privado estiver instalado, ele deverá ser testado para garantir que esteja funcionando conforme o esperado.

Ao testar o gateway de API privado, você deve ter uma API Manager API válida. na organização associada ao gateway de API privado.

Teste a API usando um API Manager URL do serviço API neste formato:

https://JBExample123456.jitterbit.net/Development/1/customer

Se a API estiver funcionando corretamente, ela poderá ser usada para testar uma URL de API privada.

Usando seu subdomínio e domínio, substitua o domínio e o subdomínio do Jitterbit, mantendo o mesmo caminho.

Usando o subdomínio (mysubdomain) e domínio (example) como mysubdomain.example.com, a URL do serviço da API seria alterada para esta URL da API privada:

https://mysubdomain.example.com/Development/1/customer

Para testar se uma configuração de proxy está funcionando, anexe ?debug para a URL:

https://mysubdomain.example.com/Development/1/customer?debug

A saída é exibida:

Proxy enabled: {proxyUri}

Onde {proxyUri} é o valor fornecido durante a configuração.

Autoteste do gateway de API privada

O gateway de API privado inclui um autoteste, acessível usando o --test opção na linha de comando.

Após um login bem-sucedido, o autoteste é executado por meio de uma série de testes automáticos que incluem a importação de um projeto e uma API integrados e, em seguida, a chamada da API por meio do gateway para garantir a configuração adequada.

A API é criada com a opção SSL only habilitada, o que significa que o acesso à URL do gateway da API privada será testado somente por HTTPS. Para permitir o acesso por HTTP, você pode desabilitar a opção SSL only na configuração da API após a criação da API de teste.

Uma URL de API deve estar disponível na sua assinatura para que o autoteste seja bem-sucedido.

Reinicie um gateway de API privado

Talvez seja necessário parar, iniciar ou reiniciar o gateway de API privado para fazer alterações de configuração adicionais, atualizar ou diagnosticar e resolver problemas. Para fazer isso, use o utilitário de configuração e estas opções:

# Stop the private API gateway:
/usr/bin/jitterbit-api-gateway-config -s stop

# Start the private API gateway:
/usr/bin/jitterbit-api-gateway-config -s start

# Restart the private API gateway:
/usr/bin/jitterbit-api-gateway-config -s restart

# Private API gateway Configuration help:
/usr/bin/jitterbit-api-gateway-config -h

# Configure the private API gateway:
/usr/bin/jitterbit-api-gateway-config

# Testing the private API gateway by using its self-test:
/usr/bin/jitterbit-api-gateway-config --test

Atualizar um gateway de API privado

Para encontrar a versão do gateway de API privada atualmente em execução na sua máquina, use este comando:

/usr/bin/jitterbit-api-gateway-config --version

A saída é exibida:

Version: x.x.x.x
Build Date: 20XX/XX/XX 00:00

É possível atualizar um gateway de API privado para uma versão posterior sem desinstalar a versão anterior do gateway, mesmo ao atualizar de uma versão 10.x para uma 11.x.

Para atualizar um gateway de API privado para uma versão posterior, siga estas etapas:

  1. Baixe a versão mais recente do software do gateway de API privado por meio de Downloads página. Se necessário, versões mais antigas do software podem ser obtidas em suporte Jitterbit.

  2. Crie um backup do arquivo de configuração do gateway de API privado existente. O arquivo de configuração do gateway de API privado está localizado neste diretório:

    /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml

  3. Ao atualizar de uma versão 10.61 ou anterior do gateway de API privado, crie um backup dos arquivos de certificado SSL. Os arquivos de certificado SSL do gateway de API privado estão localizados nestes diretórios:

    /usr/local/openresty/nginx/ssl/nginx.crt
/usr/local/openresty/nginx/ssl/nginx.key

    Nota

    Para o gateway de API privado versão 10.62 ou posterior, não é necessário fazer um backup ou copiar os arquivos de certificado SSL. Esses arquivos são retidos durante uma atualização.

  4. Os comandos usados para atualizar um gateway de API privado são os mesmos usados durante a instalação inicial. Siga as instruções para Etapa 2: Instalar o software do gateway de API privado.

  5. Copie o backup do arquivo de configuração do gateway de API privada e dos arquivos de certificado SSL (se aplicável) para a nova instalação do gateway de API privada.

  6. Opcionalmente, execute a ferramenta de configuração de linha de comando para fazer alterações de configuração adicionais. Você pode querer fazer isso se estiver usando novas definições de configuração que estão disponíveis em uma versão posterior do software de gateway de API privada.

    /usr/bin/jitterbit-api-gateway-config

    Para todas as opções de configuração, consulte Etapa 4: Configurar o gateway de API privado.

  7. Reinicie o gateway de API privado:

    /usr/bin/jitterbit-api-gateway-config -s restart

Nota

Após uma atualização, o arquivo de configuração do gateway de API privado pode encontrar erros em versões mais recentes do gateway de API privado. Nesses casos, garanta que a etapa 5 da atualização seja bem-sucedida.

Desinstalar um gateway de API privado

Use este comando para desinstalar um gateway de API privado em distribuições Linux baseadas em RPM:

RHEL or Amazon Linux AMI 2
yum remove jitterbit-api-gateway

Use este comando para desinstalar um gateway de API privado em distribuições Linux baseadas em Debian:

Debian or Ubuntu
apt-get remove jitterbit-api-gateway

Para concluir a desinstalação, execute estes comandos:

Para distribuições Linux baseadas em Debian que usam o gateway de API privado versão 10.62 ou posterior, execute este comando:

apt-get purge jitterbit-api-gateway

Para distribuições Linux baseadas em RPM que usam o gateway de API privado versão 10.62 ou posterior, execute este comando:

yum remove jitterbit-api-gateway

Para distribuições Linux baseadas em RPM e Debian (todas as versões de gateway de API privado), execute estes comandos:

rm -rf /usr/local/jitterbit-api-gateway/
rm -rf /usr/local/openresty/
rm -rf /usr/local/hostedfiles/