Esta página foi traduzida pela API Cloud Translation.

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:

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. 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.
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 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

Para ter as permissões necessárias para criar o conector personalizado, peça ao administrador para conceder a você Papel do IAM Administrador de conectores personalizados (roles/connectors.customConnectorAdmin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
Ative a API Connector:
Ative a API Connector

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 com o back-end por meio de 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

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"
Clique em Criar novo para abrir a página Criar conector personalizado.
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.
  Observação : verifique se o bucket do Cloud Storage está com a prevenção de acesso público desativada.
Clique em Próxima.
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 OpenAPI ou faça upload do arquivo de especificação em um bucket do Cloud Storage.
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. 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 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 seguintes exemplos de comandos mostram como criar um conector personalizado usando as APIs Integration Connectors:

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.

Configure a versão do conector personalizado.

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"

Substitua:

SPECIFICATION_URL: o URL de especificação OpenAPI. Por 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

No Console, acesse a página Integration Connectors > Custom connectors, selecione ou crie um projeto do Google Cloud.
Acessar a página "Conectores personalizados"
Clique em Criar novo para abrir a página Criar conector personalizado.
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 o logotipo do conector.
  Observação : verifique se o bucket do Cloud Storage está com a prevenção de acesso público desativada.
Clique em Próxima.
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 da API aberta ou faça upload do arquivo de especificação para um bucket do Cloud Storage.
Clique em Próxima.
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. Porta: insira o número da porta do serviço intermediário.
Clique em Próxima.
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.
Clique em Próxima.
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: 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.
- Como alternativa, selecione Required para especificar que a variável é obrigatória.
Observação: você vai precisar inserir os valores das variáveis configuradas ao criar uma conexão.
Clique em Próxima.
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. Você pode acessar os detalhes da versão em 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.

API

Os seguintes exemplos de comandos mostram como criar um conector personalizado usando as APIs Integration Connectors:

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.

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"

Substitua:

SPECIFICATION_URL: o URL de especificação OpenAPI. Por 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 da versão do conector personalizado. Por exemplo, 1.

Observação: este exemplo de chamada de API usa a autenticação Username and Password. Com base nos requisitos, é possível usar um tipo de autenticação diferente.

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:

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"
Clique em Criar nova para abrir a página Criar conexão.
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.
Clique em Próxima.
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, 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. 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 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. Também é possível clicar em Adicionar rótulo para adicioná-lo a conexão na forma de um par de chave-valor.
Clique em Próxima.
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, 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. 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.
Clique em Próxima.
Revise os detalhes da configuração da conexão e clique em Criar.

Se a criaçã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:

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, os Conectores de integração validam a especificação. 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 projetos do Google Cloud que têm 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.