Esta página foi traduzida pela API Cloud Translation.

Crie um conector personalizado

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

Para estabelecer a conetividade ao seu back-end através de um conetor personalizado, tem de realizar as seguintes tarefas:

Crie um conetor personalizado: nesta tarefa, vai definir o contrato entre os Integration Connectors e o seu ponto final (back-end) fornecendo a especificação OpenAPI do ponto final. Atualmente, apenas a versão 3.0 da OpenAPI e todas as suas versões secundárias são suportadas. A especificação da especificação é uma atividade única.
Crie uma ligação de conetor personalizado: nesta tarefa, vai configurar os detalhes de ligação do seu back-end, como o nome do anfitrião e a autenticação. Para um conetor personalizado específico, pode criar as ligações que precisar.

Para compreender a diferença entre um conector e uma associação, consulte o artigo Conector versus associação.

Antes de começar

Para receber as autorizações de que precisa para criar o conetor personalizado, peça ao seu administrador para lhe conceder a função IAM Administrador de conetores personalizados (roles/connectors.customConnectorAdmin) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.
Ative a API Connector:
Ative a API Connector

Crie um conector personalizado

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

Conetividade direta ao ponto final público do seu back-end.
Conetividade indireta ao seu back-end através de um ponto final público intermediário.

Os passos de criação de conetores personalizados variam ligeiramente para estes dois padrões.

Crie com conetividade direta

Para criar um conector personalizado com conetividade direta ao ponto final do seu back-end, siga estes passos:

Consola

Na Console, aceda à página Conetores de integração > Conetores personalizados e, em seguida, selecione ou crie um Google Cloud projeto.
Aceda à página Conetores personalizados
Clique em Criar novo para abrir a página Criar conetor personalizado.
Na secção Detalhes do conetor, defina os seguintes campos:
1. Nome do conetor: introduza um nome para o conetor.
2. Nome a apresentar: introduza um nome a apresentar para o conetor.
3. Descrição: introduza uma descrição.
4. Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
5. Logótipo: carregue a imagem para um contentor do Cloud Storage para a usar como logótipo do conector.
  Nota: certifique-se de que o seu contentor do Cloud Storage tem a prevenção de acesso público desativada.
Clicar em Seguinte.
Na secção Especificação do conetor, defina os seguintes campos:
1. Tipo de conetor personalizado: selecione o tipo de conetor personalizado.
2. Especificação do conector: introduza o URL público da especificação da API aberta ou carregue o ficheiro de especificação para um contentor do Cloud Storage.
Reveja os detalhes da configuração do conetor e, de seguida, clique em Criar.

Se a criação do conector for bem-sucedida, o conector criado recentemente é apresentado na página Aceda à página Conetores personalizados e, se for um novo conector, também é criada uma primeira versão do conector. Pode ver os detalhes da versão no separador Versão da página Detalhes do conetor personalizado. Para mais informações, consulte .

No entanto, tenha em atenção que, para estabelecer ligação ao seu back-end, tem de criar uma ligação para o conector recém-criado. Para mais informações, consulte o artigo Crie uma ligação de conetor personalizado.

API

Os comandos de exemplo seguintes mostram como criar um conector personalizado através das APIs Integration Connectors:

Crie o conetor.

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 o seguinte:

CUSTOM_CONNECTOR_NAME: um nome para o conetor personalizado.
PROJECT_ID: o ID do seu projeto Google Cloud .
UNIQUE_IDENTIFIER: um identificador exclusivo do conetor. Por exemplo, custom-connector-1.

Configure a versão do conetor 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 o seguinte:

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 seu projeto Google Cloud .
VERSION_NUMBER: um número de versão para o conector. Por exemplo, 2.

Crie com conetividade indireta

Para criar um conector personalizado que se ligue ao seu back-end através de um ponto final intermediário, siga estes passos:

Consola

Na Console, aceda à página Conetores de integração > Conetores personalizados e, em seguida, selecione ou crie um Google Cloud projeto.
Aceda à página Conetores personalizados
Clique em Criar novo para abrir a página Criar conetor personalizado.
Na secção Detalhes do conetor, defina os seguintes campos:
1. Nome do conetor: introduza um nome para o conetor.
2. Nome a apresentar: introduza um nome a apresentar para o conetor.
3. Descrição: introduza uma descrição.
4. Configurar destino do conetor para acesso de back-end: ative esta opção. Isto mostra as secções de configuração adicionais na página.
5. Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
6. Logótipo: carregue a imagem para um contentor do Cloud Storage para a usar como logótipo do conector.
  Nota: certifique-se de que o seu contentor do Cloud Storage tem a prevenção de acesso público desativada.
Clicar em Seguinte.
Na secção Especificação do conetor, defina os seguintes campos:
1. Tipo de conetor personalizado: selecione o tipo de conetor personalizado.
2. Especificação do conector: introduza o URL público da especificação da API aberta ou carregue o ficheiro de especificação para um contentor do Cloud Storage.
Clicar em Seguinte.
Na secção Destino do conetor, defina os seguintes campos:
1. Tipo de destino: selecione Endereço do anfitrião.
2. Anfitrião: introduza o nome do anfitrião onde o seu serviço intermediário está a ser executado e inclua o esquema http:// ou https://.
3. Porta: introduza o número da porta do seu serviço intermediário.
Clicar em Seguinte.
Na secção Autenticação do conetor, selecione o tipo de autenticação do serviço intermediário e, de seguida, introduza os detalhes correspondentes conforme solicitado. Este passo destina-se a configurar a autenticação dos Integration Connectors para o serviço intermediário.
Não é possível configurar a configuração de autenticação do serviço intermediário para o back-end nos Integration Connectors. Cabe ao serviço intermediário decidir como quer autenticar-se junto do back-end.

Pode usar os seguintes tipos de autenticação para autenticar o serviço intermediário:
- Autenticação da conta de serviço
- Autenticação de chaves da API
- OAuth 2.0 – Autenticação de credenciais de cliente
- Autenticação básica
- Autenticação Digest
Se o acesso aos recursos da API for ilimitado e não exigir autenticação, selecione Sem autenticação.
Clicar em Seguinte.
Na secção Variáveis de back-end, introduza os valores que quer enviar para o back-end através do serviço intermediário. Tem de configurar os valores como pares de chave-valor. Para introduzir um par de chave-valor, clique em Adicionar variável e, de seguida, defina os seguintes campos:
- Chave: introduza o nome da chave.
- Tipo de valor: selecione o tipo de dados da variável.
- Nome a apresentar: introduza um nome a apresentar.
- Localização: especifique como 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.
- Opcionalmente, selecione Required para especificar que a variável é uma variável obrigatória.
Nota: é-lhe pedido que introduza os valores das variáveis configuradas quando cria uma associação.
Clicar em Seguinte.
Reveja os detalhes da configuração do conetor e, de seguida, clique em Criar.

Se a criação do conector for bem-sucedida, o conector criado recentemente é apresentado na página de conectores personalizados e, se for um novo conector, também é criada uma primeira versão do conector. Pode ver os detalhes da versão no separador Versão da página Detalhes do conetor personalizado. Para obter informações sobre como criar e editar uma versão do conetor personalizado, consulte Faça a gestão das versões do conetor personalizado.

Configure a autenticação

Introduza os detalhes com base na autenticação que quer usar.

Autenticação da conta de serviço
Selecione esta opção para fazer a autenticação através de uma conta de serviço do Google Cloud. Certifique-se de que forneceu à conta de serviço as funções e as autorizações de IAM relevantes necessárias para a autenticação.
- Âmbitos: selecione os âmbitos OAuth 2.0 necessários no menu pendente. Para mais informações, consulte os Âmbitos de acesso.
Autenticação de chave da API
Selecione esta opção para fazer a autenticação através de uma chave de API.
- Chave da API: selecione o segredo do Secret Manager da chave da API.
- Versão do Secret: selecione a versão do Secret.
- Nome do parâmetro da chave da API: introduza um nome de parâmetro para a chave da API. Uma chave da API é enviada para o seu servidor de back-end como um par de chave-valor. O valor que introduzir aqui vai ser usado como o nome da chave para a chave da API que selecionou anteriormente.
- Localização da chave da API: selecione onde quer adicionar a chave da API no pedido.
OAuth 2.0 – Concessão de credenciais de cliente
- ID de cliente: o ID de cliente a usar para a autenticação no serviço intermediário.
- Segredo do cliente: segredo do Secret Manager que contém o segredo do cliente para autenticação no serviço intermediário.
- Formato do pedido para o token de acesso: formato do pedido a usar em pedidos feitos para obter o token de acesso do servidor de autorização. Selecione body para transmitir o ID de cliente e o segredo como um corpo do pedido ou header para os transmitir como um cabeçalho codificado.
- Caminho do pedido de token: caminho do pedido a anexar ao URL do servidor de autorização para obter o URL do token de acesso.
Autenticação básica
- Nome de utilizador: nome de utilizador usado para autenticação no serviço intermediário.
- Palavra-passe: Secret do Secret Manager que contém a palavra-passe associada ao nome de utilizador facultado.
Autenticação por resumo
- Nome de utilizador: nome de utilizador usado para autenticação no serviço intermediário.
- Palavra-passe: Secret do Secret Manager que contém a palavra-passe associada ao nome de utilizador facultado.

API

Os comandos de exemplo seguintes mostram como criar um conector personalizado através das APIs Integration Connectors:

Crie o conetor.

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 o seguinte:

CUSTOM_CONNECTOR_NAME: um nome para o conetor personalizado.
PROJECT_ID: o ID do seu projeto Google Cloud .
UNIQUE_IDENTIFIER: um identificador exclusivo do conetor. Por exemplo, custom-connector-1.

Configure a versão do conetor 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 o seguinte:

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 seu projeto Google Cloud .
USERNAME: nome de utilizador 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 anfitrião 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.

Nota: esta chamada API de exemplo usa a autenticação Username and Password. Com base nos seus requisitos, pode usar um tipo de autenticação diferente.

Crie uma ligação de conetor personalizado

Depois de criar o conector personalizado, para estabelecer ligação ao seu back-end, tem de criar uma ligação do tipo de conector personalizado. Seguem-se os passos gerais para criar uma nova associação:

Na Cloud Console, aceda à página Integration Connectors > Ligações e, de seguida, selecione ou crie um projeto do Google Cloud.
Aceda à página Ligações
Clique em Criar novo para abrir a página Criar associação.
Na secção Localização, selecione uma localização para a ligação no campo Região.
Para ver a lista de todas as regiões suportadas, consulte o artigo Localizações.
Clicar em Seguinte.
Na secção Detalhes da associação, defina os seguintes campos:
1. Conector: selecione o conector personalizado na lista pendente de conectores disponíveis.
2. Versão do conetor: selecione a versão do conetor na lista pendente de versões disponíveis.
3. No campo Nome da associação, introduza um nome para a associação.
  Os nomes das associações têm de cumprir os seguintes critérios:
  - Os nomes das associações podem usar letras, números ou hífenes.
  - As letras têm de ser minúsculas.
  - Os nomes das associações têm de começar com uma letra e terminar com uma letra ou um número.
  - Os nomes das associações não podem exceder 63 carateres.
4. Opcionalmente, introduza uma Descrição para a associação.
5. Opcionalmente, selecione Ativar registo na nuvem para ativar o registo na nuvem.
6. Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
7. Opcionalmente, configure as definições do nó de associação:
  - Número mínimo de nós: introduza o número mínimo de nós de ligação.
  - Número máximo de nós: introduza o número máximo de nós de ligação.
  Um nó é uma unidade (ou uma réplica) de uma ligação que processa transações. São necessários mais nós para processar mais transações para uma ligação e, inversamente, são necessários menos nós para processar menos transações. Para compreender como os nós afetam os preços dos conectores, consulte o artigo Preços dos nós de ligação. Se não introduzir valores, por predefinição, os nós mínimos são definidos como 2 (para uma melhor disponibilidade) e os nós máximos são definidos como 50.
8. Opcionalmente, clique em Adicionar etiqueta para adicionar uma etiqueta à associação sob a forma de um par de chave-valor.
Clicar em Seguinte.
Se o conector usar um serviço intermediário para se ligar ao seu back-end, faça o seguinte:
Na secção Destinos, defina os seguintes campos:
1. Tipo de destino: selecione Endereço do anfitrião.
2. Anfitrião: introduza o nome do anfitrião onde o seu serviço intermediário está a ser executado e inclua o esquema http:// ou https://.
3. Porta: introduza o número da porta do seu serviço intermediário.
Por predefinição, o campo de destino contém o URL da especificação da especificação OpenAPI. Quando existem vários URLs de servidor, é apresentado o primeiro.
Clicar em Seguinte.
Na secção Autenticação, introduza os detalhes de autenticação para o seu back-end.
- Se se ligar diretamente ao seu back-end, os Integration Connectors pedem-lhe que configure a autenticação para o seu back-end.
- Se se ligar indiretamente ao seu back-end através de um serviço intermediário, os Integration Connectors não lhe pedem que configure detalhes de autenticação. Quando cria o conetor, já configurou a autenticação entre os Integration Connectors e o serviço intermediário. Os conectores de integração não requerem que configure a autenticação entre o serviço intermediário e o back-end. Cabe ao serviço intermediário decidir como quer fazer a autenticação com o back-end.
Clicar em Seguinte.
Reveja os detalhes da configuração da associação e, de seguida, clique em Criar.

Se a criação da associação for bem-sucedida, esta é apresentada na página Todas as associações, e a associação fica disponível na integração de aplicações. Pode usar a ligação na sua integração através da tarefa Conectores.

Considerações

Considere os seguintes pontos ao criar um conetor personalizado:

Os conectores de integração só suportam a versão 3.0 da OpenAPI e todas as respetivas versões secundárias.
A especificação da API aberta não é validada durante a criação do conetor personalizado. Quando cria uma associação para o conetor personalizado, os Integration Connectors validam a especificação e, se tiver erros, a associação fica no estado Error.
Os conectores de integração não fazem distinção entre entidades e ações. Assim, as entidades e as ações do seu back-end são apresentadas como Actions no conector personalizado.
Os conetores personalizados não são suportados em Google Cloud projetos que tenham os VPC Service Controls ativados.
Tanto o ponto final da especificação da API aberta como o ponto final do back-end devem ser acessíveis publicamente. Isto significa que não pode estabelecer uma ligação privada ao seu back-end.
O tipo de conteúdo multimédia multipartes não é suportado na especificação da API aberta.
Não pode editar os detalhes da versão de um conector personalizado.