Criar um conector personalizado

Esta página descreve como criar um conector personalizado. Para entender o que é um conector personalizado, consulte Conectores personalizados.

Para estabelecer a conectividade com o back-end usando um conector personalizado, você precisa fazer o seguinte:

  1. Criar um conector personalizado: nesta tarefa, você vai definir o contrato entre os conectores de integração e seu endpoint (back-end) fornecendo a especificação da OpenAPI do endpoint. No momento, somente a versão 3.0 da OpenAPI e todas as versões secundárias dela são compatíveis. Especificar a especificação é uma atividade única.
  2. Criar uma conexão de conector personalizada: nesta tarefa, você vai configurar os detalhes de conexão do seu back-end, como o nome do host e a autenticação. Para um conector personalizado específico, você pode criar quantas conexões precisar.

Para entender a diferença entre um conector e uma conexão, consulte Conector x conexão.

Antes de começar

Criar um conector personalizado

Conforme descrito nos cenários de conectividade do back-end, os conectores personalizados podem ter qualquer um dos seguintes padrões de conectividade:

  • Conectividade direta ao endpoint público do back-end.
  • Conectividade indireta ao back-end por um endpoint público intermediário.

As etapas de criação de conectores personalizados variam um pouco para esses dois padrões.

Criar com conectividade direta

Para criar um conector personalizado com conectividade direta ao endpoint do back-end, siga estas etapas:

Console

  1. No Console, acesse a página Integration Connectors > Custom connectors e selecione ou crie um projeto Google Cloud .

    Acessar a página "Conectores personalizados"

  2. Clique em Criar novo para abrir a página Criar conector personalizado.
  3. Na seção Detalhes do conector, defina os seguintes campos:
    1. Nome do conector: insira um nome para o conector.
    2. Nome de exibição: insira um nome de exibição para o conector.
    3. Descrição: digite uma descrição.
    4. Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
    5. Logotipo: faça upload da imagem em um bucket do Cloud Storage para usá-la como o logotipo do conector.
  4. Clique em Próxima.
  5. Na seção Especificação do conector, defina os seguintes campos:
    1. Tipo de conector personalizado: selecione o tipo de conector personalizado.
    2. Especificação do conector: insira o URL público da especificação da API aberta ou faça upload do arquivo de especificação para um bucket do Cloud Storage.
  6. Revise os detalhes de configuração do conector e clique em Criar.

Se a criação for bem-sucedida, o conector recém-criado será exibido na página Acessar a página "Conectores personalizados". Se for um conector novo, uma primeira versão dele também será criada. Confira os detalhes da versão na guia Versão da página Detalhes do conector personalizado. Para mais informações, consulte .

No entanto, para se conectar ao seu back-end, você precisa criar uma conexão para o conector recém-criado. Para mais informações, consulte Criar uma conexão de conector personalizada.

API

Os comandos de exemplo a seguir mostram como criar um conector personalizado usando as APIs Integration Connectors:

  1. Crie o conector. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    Substitua:

    • CUSTOM_CONNECTOR_NAME: um nome para o conector personalizado.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • UNIQUE_IDENTIFIER: um identificador exclusivo do conector. Por exemplo, custom-connector-1.
  2. Configure a versão personalizada do conector. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL",}' \
"https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"

    3. Substitua:

    • SPECIFICATION_URL: o URL da especificação da API aberta. Por exemplo, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • VERSION_NUMBER: um número de versão do conector. Por exemplo, 2.

Criar com conectividade indireta

Para criar um conector personalizado que se conecte ao back-end por um endpoint intermediário, siga estas etapas:

Console

  1. No Console, acesse a página Integration Connectors > Custom connectors e selecione ou crie um projeto Google Cloud .

    Acessar a página "Conectores personalizados"

  2. Clique em Criar novo para abrir a página Criar conector personalizado.
  3. Na seção Detalhes do conector, defina os seguintes campos:
    1. Nome do conector: insira um nome para o conector.
    2. Nome de exibição: insira um nome de exibição para o conector.
    3. Descrição: digite uma descrição.
    4. Configurar o destino do conector para acesso ao back-end: ative essa opção. Isso mostra as seções de configuração adicionais na página.
    5. Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
    6. Logotipo: faça upload da imagem em um bucket do Cloud Storage para usá-la como o logotipo do conector.
  4. Clique em Próxima.
  5. Na seção Especificação do conector, defina os seguintes campos:
    1. Tipo de conector personalizado: selecione o tipo de conector personalizado.
    2. Especificação do conector: insira o URL público da especificação da API aberta ou faça upload do arquivo de especificação para um bucket do Cloud Storage.
  6. Clique em Próxima.
  7. Na seção Destino do conector, defina os seguintes campos:
    1. Tipo de destino: selecione Endereço do host.
    2. Host: insira o nome do host em que o serviço intermediário está sendo executado.
    3. Porta: insira o número da porta do serviço intermediário.
  8. Clique em Próxima.
  9. Na seção Autenticação do conector, selecione o tipo de autenticação do serviço intermediário e insira os detalhes correspondentes conforme solicitado. Nesta etapa, você vai configurar a autenticação dos conectores de integração para o serviço intermediário.

    A configuração de autenticação do serviço intermediário para o back-end não pode ser configurada nos conectores de integração. Isso depende do serviço intermediário.

    É possível usar os seguintes tipos de autenticação para se autenticar no serviço intermediário:

    • Autenticação da conta de serviço
    • Autenticação de chave de API
    • OAuth 2.0: autenticação de credenciais do cliente
    • Autenticação básica
    • Autenticação por e-mail

      • Para entender como configurar esses tipos de autenticação, consulte Configurar autenticação.

    Se o acesso aos recursos da API não tiver restrições e não exigir autenticação, selecione Nenhuma autenticação.

  10. Clique em Próxima.
  11. Na seção Variáveis de back-end, insira os valores que você quer enviar para o back-end pelo serviço intermediário. Você precisa configurar os valores como pares de chave-valor. Para inserir um par de chave-valor, clique em Adicionar variável e defina os seguintes campos:
    • Chave: insira o nome da chave.
    • Tipo de valor: selecione o tipo de dados da variável.
    • Nome de exibição: insira um nome de exibição.
    • Local: especifique como você quer que o conector envie as variáveis para o serviço intermediário. As opções disponíveis são Header, Request payload e Query parameter.
    • Como alternativa, selecione Required para especificar que a variável é obrigatória.
  12. Clique em Próxima.
  13. Revise os detalhes de configuração do conector e clique em Criar.

Se a criação do conector for bem-sucedida, o conector recém-criado será mostrado na página Conectores personalizados. Se for um conector novo, uma primeira versão dele também será criada. Confira os detalhes da versão na guia Versão da página Detalhes do conector personalizado. Para informações sobre como criar e editar uma versão de conector personalizada, consulte Gerenciar versões de conectores personalizados.

No entanto, para se conectar ao seu back-end, você precisa criar uma conexão para o conector recém-criado. Para mais informações, consulte Criar uma conexão de conector personalizada.

Configurar a autenticação

Digite os detalhes com base na autenticação que você quer usar.

  • Autenticação da conta de serviço

    Selecione essa opção para fazer a autenticação usando uma conta de serviço do Google Cloud. Verifique se você forneceu à conta de serviço os papéis e as permissões do IAM relevantes para a autenticação.

    • Escopos: selecione os escopos do OAuth 2.0 necessários no menu suspenso. Para mais informações, consulte Escopos de acesso.
  • Autenticação de chave de API

    Selecione essa opção para autenticar usando uma chave de API.

    • Chave de API: selecione o secret do Secret Manager da chave de API.
    • Versão do secret: selecione a versão do secret.
    • Nome do parâmetro da chave de API: insira um nome de parâmetro para a chave de API. Uma chave de API é enviada para o servidor de back-end como um par de chave-valor. O valor inserido aqui será usado como o nome da chave da API selecionada anteriormente.
    • Local da chave de API: selecione onde você quer adicionar a chave de API na solicitação.
  • OAuth 2.0: concessão de credenciais do cliente
    • ID do cliente: o ID do cliente a ser usado para autenticação no serviço intermediário.
    • Chave secreta do cliente: o Secret do Secret Manager que contém a chave secreta do cliente para autenticação no serviço intermediário.
    • Formato da solicitação do token de acesso: formato da solicitação a ser usado em solicitações feitas para buscar o token de acesso do servidor de autenticação. Selecione body para transmitir o ID e a chave secreta do cliente como um corpo da solicitação ou header para transmiti-las como cabeçalho codificado.
    • Caminho da solicitação do token: caminho da solicitação a ser anexado ao URL do servidor de autenticação para buscar o URL do token de acesso.
  • Autenticação básica
    • Nome de usuário: nome de usuário usado para autenticação no serviço intermediário.
    • Senha: o Secret do Secret Manager que contém a senha associada ao nome de usuário fornecido.
  • Autenticação por resumo
    • Nome de usuário: nome de usuário usado para autenticação no serviço intermediário.
    • Senha: o Secret do Secret Manager que contém a senha associada ao nome de usuário fornecido.

API

Os comandos de exemplo a seguir mostram como criar um conector personalizado usando as APIs Integration Connectors:

  1. Crie o conector. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    Substitua:

    • CUSTOM_CONNECTOR_NAME: um nome para o conector personalizado.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • UNIQUE_IDENTIFIER: um identificador exclusivo do conector. Por exemplo, custom-connector-1.
  2. Configure a versão do conector personalizado e a autenticação. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL", \
"service_account":"test-sa", \
"enable_backend_destination_config": true, \
"auth_config": { \
"auth_type":"USER_PASSWORD", \
"auth_key": "basic", \
"user_password": { \
"username":"USERNAME", \
"password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
}}, \
"backend_variable_templates": [{ \
"key":"authkey", \
"value_type":"SECRET", \
"display_name":"Authorization Key", \
"required":true, \
"location_type": "HEADER" \
}], \
"destination_configs":[{ \
"key":"base_url", \
"destinations": [{ \
"host":"DESTINATION_HOST_ADDRESS" \
}]} \
]}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"

    3. Substitua:

    • SPECIFICATION_URL: o URL da especificação da API aberta. Por exemplo, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • USERNAME: nome de usuário para autenticação com o serviço intermediário.
    • SECRET_VERSION_NUMBER: o número da versão do secret do Secret Manager. Por exemplo, 2.
    • DESTINATION_HOST_ADDRESS: endereço do host do serviço intermediário. Por exemplo, http://www.test.com:80.
    • CONNECTOR_VERSION_NUMBER: o número da versão do conector personalizado. Por exemplo, 1.

Criar uma conexão de conector personalizado

Depois de criar o conector personalizado, para se conectar ao back-end, você precisa criar uma conexão do tipo de conector personalizado. Confira a seguir as etapas gerais para criar uma nova conexão:

  1. No console do Cloud, acesse a página Integration Connectors > Conexões e selecione ou crie um projeto do Google Cloud.

    Acessar a página "Conexões"

  2. Clique em Criar novo para abrir a página Criar conexão.
  3. Na seção Local, selecione um local para a conexão no campo Região.

    Para conferir a lista de todas as regiões com suporte, consulte Locais.

  4. Clique em Próxima.
  5. Na seção Detalhes da conexão, defina os seguintes campos:
    1. Conector: selecione o conector personalizado na lista suspensa de conectores disponíveis.
    2. Versão do conector: selecione a versão do conector na lista suspensa de versões disponíveis.
    3. No campo Nome da conexão, insira um nome para a conexão.

      Os nomes de conexão precisam atender aos seguintes critérios:

      • Os nomes de conexões podem usar letras, números ou hifens.
      • As letras precisam ser minúsculas.
      • Os nomes das conexões precisam começar com uma letra e terminar com uma letra ou um número.
      • Os nomes das conexões não podem exceder 63 caracteres.
    4. Se quiser, insira uma Descrição para a conexão.
    5. Opcionalmente, selecione Ativar o Cloud Logging para ativar a geração de registros na nuvem.
    6. Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
    7. Opcionalmente, defina as Configurações do nó de conexão:

      • Número mínimo de nós: digite o número mínimo de nós de conexão.
      • Número máximo de nós: digite o número máximo de nós de conexão.

      Um nó é uma unidade (ou réplica) de uma conexão que processa transações. Mais nós são necessários para processar mais transações para uma conexão e, por outro lado, menos nós são necessários para processar menos transações. Para entender como os nós afetam os preços do conector, consulte Preços dos nós de conexão. Se você não inserir qualquer valor, por padrão, os nós mínimos serão definidos como 2 (para melhor disponibilidade) e os nós máximos serão definidos como 50.

    8. Outra opção é clicar em Adicionar rótulo para adicionar um rótulo à conexão na forma de um par de chave-valor.
  6. Clique em Próxima.
  7. Na seção Autenticação, insira os detalhes de autenticação do back-end.
    • Se você se conectar diretamente ao back-end, os Integration Connectors vão solicitar que você configure a autenticação.
    • Se você se conectar indiretamente ao back-end por um serviço intermediário, os conectores de integração não vão solicitar a configuração dos detalhes de autenticação. Ao criar o conector, você já terá configurado a autenticação entre os Integration Connectors e o serviço intermediário. Os conectores de integração não exigem que você configure a autenticação entre o serviço intermediário e o back-end. Isso depende do serviço intermediário sobre como ele quer se autenticar com o back-end.
  8. Clique em Próxima.
  9. Revise os detalhes da configuração da conexão e clique em Criar.

Se a criação da conexão for bem-sucedida, ela vai ser listada na página Todas as conexões e vai ficar disponível na integração de aplicativos. É possível usar a conexão na integração usando a tarefa de conectores.

Considerações

Considere os seguintes pontos ao criar um conector personalizado:

  • Os conectores de integração são compatíveis apenas com a versão 3.0 da OpenAPI e todas as versões secundárias dela.
  • A especificação da API aberta não é validada durante a criação de conectores personalizados. Quando você cria uma conexão para o conector personalizado, os Conectores de integração validam a especificação e, se houver erros, a conexão estará no estado Error.
  • Os Integration Connectors não diferenciam entidades e ações. Portanto, as entidades e ações do back-end serão listadas como Actions no conector personalizado.
  • Os conectores personalizados não são compatíveis com Google Cloud projetos que têm o VPC Service Controls ativado.
  • O endpoint da especificação da API aberta e o endpoint de back-end precisam estar acessíveis publicamente. Isso significa que não é possível estabelecer uma conexão particular com seu back-end.
  • O tipo de mídia com várias partes não é aceito na especificação da API aberta.
  • Não é possível editar os detalhes da versão de um conector personalizado.