Criar um conector personalizado

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

Para estabelecer a conectividade com seu back-end usando um conector personalizado, você precisa realizar as seguintes tarefas:

  1. Criar um conector personalizado: nesta tarefa, você vai definir o contrato entre o Integration Connectors e seu endpoint (back-end) fornecendo a especificação OpenAPI do endpoint. Atualmente, só há suporte para a versão 3.0 da OpenAPI e todas as versões secundárias. Especificar a especificação é uma atividade que só ocorre uma vez.
  2. Criar uma conexão de conector personalizada: nesta tarefa, você vai configurar os detalhes de conexão do back-end, como o nome do host e a autenticação. Para um personalizado específico, você pode criar quantas conexões precisar.

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

Antes de começar

Verifique se o usuário que está criando o conector personalizado tem uma das seguintes opções Papéis do IAM:

Criar um conector personalizado

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

  • Conectividade direta com o endpoint público do back-end.
  • Conectividade indireta com o back-end por meio de um endpoint público intermediário.

As etapas de criação do conector personalizado variam um pouco nesses dois padrões.

Criar com conectividade direta

Para criar um conector personalizado com conectividade direta ao endpoint do back-end, faça o seguinte: siga estas etapas:

Console

  1. No console, acesse a página Integration Connectors > Custom Connectors e depois selecione ou crie um projeto do 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: digite um nome para o conector.
    2. Nome de exibição: digite 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 tem os papéis necessários.
    5. Logotipo: faça upload da imagem em um bucket do Cloud Storage para usá-la como logotipo do conector.
  4. Clique em Next.
  5. Na seção Especificação do conector, defina os seguintes campos:
    1. Tipo de conector personalizado: selecione o tipo personalizado.
    2. Especificação do conector: insira o URL público da especificação OpenAPI ou faça upload do arquivo de especificação em um bucket do Cloud Storage.
  6. 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á exibido no Acesse a página "Conectores personalizados" e, se ele for um novo conector, a primeira versão o conector também é criado. Você pode acessar os detalhes da versão em Versão da página Detalhes do conector personalizado. Para mais informações, consulte .

No entanto, para se conectar ao 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 seguintes exemplos de comandos 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 do 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 de especificação OpenAPI. Para exemplo: https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: o ID do projeto do 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 conecta ao back-end por meio de um endpoint intermediário, siga estas etapas:

Console

  1. No console, acesse a página Integration Connectors > Custom Connectors e depois selecione ou crie um projeto do 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: digite um nome para o conector.
    2. Nome de exibição: digite 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 esta opção. Isso mostra as seções de configuração adicionais na página.
    5. Conta de serviço: selecione uma que tenha os papéis necessários.
    6. Logotipo: faça upload da imagem em um bucket do Cloud Storage para usá-la como logotipo do conector.
  4. Clique em Next.
  5. Na seção Especificação do conector, defina os seguintes campos:
    1. Tipo de conector personalizado: selecione o tipo personalizado.
    2. Especificação do conector: insira o URL público da especificação OpenAPI ou faça upload do arquivo de especificação em um bucket do Cloud Storage.
  6. Clique em Next.
  7. Na seção Destino do conector, defina os seguintes campos:
    1. Tipo de destino: selecione Endereço do host.
    2. Host: digite o nome do host no qual o serviço intermediário está sendo executado.
    3. Port: digite o número da porta do serviço intermediário.
  8. Clique em Next.
  9. Na seção Autenticação do conector, selecione o tipo de autenticação do serviço intermediário insira os detalhes correspondentes quando solicitado. Esta etapa é configurar a autenticação dos Integration Connectors para o serviço intermediário.

    A autenticação a configuração do serviço intermediário para o back-end não pode ser definida nos Integration Connectors. Cabe ao serviço intermediário decidir como quer autenticar com o back-end.

  10. Clique em Next.
  11. Na seção Variáveis de back-end, insira os valores que 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: digite 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.
    • Se quiser, selecione Required para especificar a variável é uma variável obrigatória.
    .
  12. Clique em Next.
  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á exibido na página Personalizada de conectores, e, se for um conector novo, a primeira versão o conector também é criado. Você pode acessar os detalhes da versão em Versão da página Detalhes do conector personalizado. Para informações sobre criar e editar uma versão personalizada do conector, consulte Gerenciar versões personalizadas do conector.

No entanto, para se conectar ao 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 seguintes exemplos de comandos 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 do Google Cloud.
    • UNIQUE_IDENTIFIER: um identificador exclusivo do conector. Por exemplo, custom-connector-1.
  2. Configure a autenticação e 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", \
"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 de especificação OpenAPI. Para exemplo: https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: o ID do projeto do 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 personalizado da versão do conector. Por exemplo, 1.
    .

Criar uma conexão de conector personalizada

Depois de criar seu conector personalizado, para se conectar ao back-end, você precisa criar uma conexão do tipo de conector personalizado. A seguir estão os 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 nova 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 Next.
  5. Na seção Detalhes da conexão, defina os seguintes campos:
    1. Conector: selecione seu 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, digite um nome.

      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. Também é possível digitar uma Descrição para a conexão.
    5. Se quiser, selecione Ativar o Cloud Logging.
    6. Conta de serviço: selecione uma conta de serviço que tem 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. Também é possível clicar em Adicionar rótulo para adicioná-lo a conexão na forma de um par de chave-valor.
  6. Clique em Next.
  7. Na seção Autenticação, insira os detalhes de autenticação. para o back-end.
    • Se você se conectar diretamente ao back-end, o Integration Connectors solicita para configurar a autenticação do back-end.
    • Se você se conectar indiretamente ao back-end por um serviço intermediário, O Integration Connectors não solicita que você configure detalhes de autenticação. Ao criar o conector, você já deve ter configurado a autenticação entre os Integration Connectors e serviço intermediário. O Integration Connectors não exige a configuração de autenticação entre o serviço intermediário e o back-end. cabe ao intermediário serviço sobre como ele quer se autenticar com o back-end.
  8. Clique em Next.
  9. Analise os detalhes da configuração da conexão e clique em Criar.

Se a conexão for criada, ela será listada na página Todas as conexões, e a conexão é disponibilizada na Application Integration. Você pode usar a conexão na sua integração pela tarefa Conectores.

Considerações

Considere os seguintes pontos ao criar um conector personalizado:

  • O Integration Connectors só é compatível com a OpenAPI versão 3.0 e todas as versões secundárias.
  • A especificação OpenAPI não é validada durante a criação do conector personalizado. Quando você cria uma conexão para o conector personalizado, o Integration Connectors valida a especificação; Se houver erros, a conexão vai ficar no estado Error.
  • O Integration Connectors não diferencia entidades e ações. Portanto, as entidades e as ações do back-end serão listadas como Actions no seu conector personalizado.
  • Não é possível usar conectores personalizados em projetos do Google Cloud com o VPC Service Controls ativado.
  • O endpoint de especificação OpenAPI e o endpoint de back-end precisam ser acessíveis publicamente. Isso significa que não é possível estabelecer conectividade particular com o back-end.
  • O tipo de mídia de várias partes não é compatível com a especificação OpenAPI.
  • Não é possível editar os detalhes da versão de um conector personalizado.