HTTP

O conetor HTTP oferece conetividade ao serviço HTTP e permite-lhe consumir APIs baseadas em HTTP. O conetor também suporta a conetividade SSL/TLS através da configuração personalizada e suporta vários mecanismos de autenticação, como a concessão de credenciais de cliente do OAuth 2.0, o básico e o resumo.

Antes de começar

Antes de usar o conector HTTP, conclua as seguintes tarefas:

  • No seu projeto do Google Cloud:
    • Certifique-se de que a conetividade de rede está configurada. Para obter informações sobre padrões de rede, consulte o artigo Conetividade de rede.
    • Conceda a função IAM roles/connectors.admin ao utilizador que está a configurar o conetor.
    • Conceda as seguintes funções de IAM à conta de serviço que quer usar para o conector:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      Uma conta de serviço é um tipo especial de Conta Google destinada a representar um utilizador não humano que precisa de autenticação e autorização para aceder a dados nas APIs Google. Se não tiver uma conta de serviço, tem de criar uma. O conector e a conta de serviço têm de pertencer ao mesmo projeto. Para mais informações, consulte Criar uma conta de serviço.

    • Ative os seguintes serviços:
      • secretmanager.googleapis.com (Secret Manager API)
      • connectors.googleapis.com (API Connectors)

      Para saber como ativar serviços, consulte o artigo Ativar serviços.

    Se estes serviços ou autorizações não tiverem sido ativados anteriormente para o seu projeto, é-lhe pedido que os ative quando configurar o conector.

Configure o conetor

Uma associação é específica de uma origem de dados. Isto significa que, se tiver muitas origens de dados, tem de criar uma associação separada para cada origem de dados. Para criar uma associação, faça o seguinte:

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

  2. Clique em + Criar novo para abrir a página Criar associação.
  3. Na secção Localização, escolha a localização para a ligação.
    1. Região: selecione uma localização na lista pendente.

      Para ver a lista de todas as regiões suportadas, consulte o artigo Localizações.

    2. Clicar em Seguinte.
  4. Na secção Detalhes da associação, conclua o seguinte:
    1. Conetor: selecione HTTP na lista pendente de conetores 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 ligação, introduza um nome para a instância de ligaçã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 49 carateres.
    4. Opcionalmente, introduza uma Descrição para a instância de associação.
    5. Opcionalmente, ative o Registo na nuvem e, em seguida, selecione um nível de registo. Por predefinição, o nível do registo está definido como Error.
    6. Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
    7. Opcionalmente, para verificar o estado da ligação, no campo Verificação do estado, especifique um URL de ponto final. O URL também pode incluir um endereço IP do anexo do ponto final. O estado está ativo por predefinição.
    8. 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.

    9. Usar proxy: selecione a caixa de verificação para configurar um servidor proxy para a ligação.
      1. Clique em + Adicionar destino.
      2. Selecione um Tipo de destino.
        • Endereço do anfitrião: especifique o nome do anfitrião ou o endereço IP do destino.

          Se quiser estabelecer uma ligação privada ao seu back-end, faça o seguinte:

    10. Opcionalmente, clique em + ADICIONAR ETIQUETA para adicionar uma etiqueta à associação sob a forma de um par chave/valor.
    11. Opcionalmente, se quiser usar SSL, selecione Ativar SSL. São apresentados os detalhes da configuração SSL.
      1. Selecione um tipo de loja fidedigna. Pode ser Público, Privado ou Ligação não segura.
      2. Selecione os certificados conforme apresentado com base na sua seleção da loja de confiança.
      3. Se usar um certificado autoassinado ou um certificado de repositório fidedigno privado, armazene o certificado de raiz como um segredo do Secret Manager no formato PEM (Privacy Enhanced Mail) e, em seguida, em Repositório fidedigno personalizado, selecione o segredo necessário.
      4. Se estiver a usar o mTLS, selecione os certificados do armazenamento de chaves na secção Armazenamento de chaves.
      5. Opcionalmente, selecione a versão do TLS.
      6. Introduza o conjunto de cifras suportado. Introduza várias suites de cifragem como valores separados por vírgulas. Para mais informações, consulte o artigo Conjuntos de cifras suportados.
    12. Clicar em Seguinte.
  5. Na secção Destinos, introduza os detalhes do anfitrião remoto (sistema de back-end) ao qual quer estabelecer ligação.
    1. Tipo de destino: selecione um Tipo de destino.
      • Para especificar o nome de anfitrião ou o endereço IP de destino, selecione Endereço do anfitrião e introduza o endereço no campo Anfitrião 1.
      • Para estabelecer uma ligação privada, selecione Anexo do ponto final e escolha o anexo necessário na lista Anexo do ponto final.

      Se quiser estabelecer uma ligação pública aos seus sistemas de back-end com segurança adicional, pode considerar configurar endereços IP estáticos de saída para as suas ligações e, em seguida, configurar as regras da firewall para permitir apenas os endereços IP estáticos específicos.

      Para introduzir destinos adicionais, clique em + Adicionar destino.

    2. Clicar em Seguinte.
  6. Na secção Autenticação, introduza os detalhes de autenticação.
    1. Selecione um Tipo de autenticação e introduza os detalhes relevantes.

      Os seguintes tipos de autenticação são suportados pela ligação HTTP:

      2. Para saber como configurar estes tipos de autenticação, consulte o artigo Configurar autenticação.

    2. Clicar em Seguinte.
  7. Rever: reveja os detalhes da ligação e da autenticação.
  8. Clique em Criar.

Configure a autenticação

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

  • Autenticação personalizada

    Os detalhes de autorização personalizados podem ser adicionados como um cabeçalho de pedido durante a execução da ação da tarefa Conetores.

  • OAuth 2.0 – Concessão de credenciais de cliente
    • ID de cliente: o ID de cliente a usar para autenticar o pedido HTTP.
    • Segredo do cliente: segredo do Secret Manager que contém o segredo do cliente para autenticar o pedido HTTP.
    • 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.
    • Prazo de validade predefinido: prazo de validade predefinido (em segundos) para o token de acesso. Este tempo é usado caso a resposta da chave de acesso não tenha um tempo de expiração. Se o valor não for fornecido, o token é atualizado em 6 horas.
  • Autenticação básica
    • Nome de utilizador: nome de utilizador usado para fazer o pedido HTTP.
    • 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 fazer o pedido HTTP.
    • Palavra-passe: Secret do Secret Manager que contém a palavra-passe associada ao nome de utilizador facultado.
  • OAuth 2.0 – Código de autorização
    • ID de cliente: ID de cliente conforme fornecido pela sua aplicação externa.
    • Âmbitos: âmbitos de autorização suportados pela sua aplicação externa.
    • Segredo do cliente: selecione o segredo do Secret Manager. Deve ter criado o segredo do Secret Manager antes de configurar esta autorização.
    • Versão do Secret: versão do Secret do Secret Manager para o segredo do cliente.
    • Opcionalmente, ative o PKCE (Proof Key for Code Exchange) se o seu servidor de back-end o suportar.
    • URL de autorização: introduza o URL de autorização da sua aplicação externa.
    • URL da chave de acesso: introduza o URL para obter a chave de acesso da sua aplicação externa.

    Para o tipo de autenticação Authorization code, depois de criar a associação, deve efetuar alguns passos adicionais para configurar a autenticação. Para mais informações, consulte Passos adicionais após a criação da associação.

  • Conta de serviço

    Selecione esta opção para fazer a autenticação através da conta de serviço que indicou nos passos anteriores ao configurar esta associação. Certifique-se de que indicou a conta de serviço que tem as funções e as autorizações do 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 token de ID da conta de serviço

    Selecione esta opção para fazer a autenticação através do token de ID gerado a partir da conta de serviço que indicou nos passos anteriores. Esta autenticação usa símbolos da Web JSON (JWT) para autenticação. O fornecedor de tokens de ID assina e emite os JWTs para autenticação através de uma conta de serviço.

    • Público-alvo: introduza os destinatários a quem o JWT se destina.
    • Nome do cabeçalho: introduza o nome do cabeçalho do token de ID gerado a usar no cabeçalho HTTP. Se não especificar nenhum valor para este campo, o valor-chave é definido como Authorization por predefinição.
  • 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.

Conjuntos de cifras suportados

Versão do TLS Conjuntos de cifras suportados
1.2
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
1.3
  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256

Passos adicionais após a criação da associação

Se selecionou OAuth 2.0 - Authorization code para a autenticação, tem de realizar os seguintes passos adicionais após criar a associação:

  1. Na página Ligações, encontre a ligação criada recentemente.

    Tenha em atenção que o Estado do novo conetor é Autorização necessária.

  2. Clique em Autorização obrigatória.

    É apresentado o painel Editar autorização.

  3. Copie o valor do URI de redirecionamento para a sua aplicação externa.
  4. Valide os detalhes da autorização.
  5. Clique em Autorizar.

    Se a autorização for bem-sucedida, o estado da ligação é definido como Ativo na página Ligações.

Nova autorização para o código de autorização

Se estiver a usar o tipo de autenticação Authorization code e tiver feito alterações de configuração na sua aplicação HTTP de back-end, tem de autorizar novamente a sua ligação HTTP. Para autorizar novamente uma associação, siga estes passos:

  1. Clique na associação necessária na página Associações.

    É apresentada a página de detalhes da associação.

  2. Clique em Editar para editar os detalhes da associação.
  3. Valide os detalhes de OAuth 2.0 – Código de autorização na secção Autenticação.

    Se necessário, faça as alterações necessárias.

  4. Clique em Guardar. Esta ação direciona para a página de detalhes da associação.
  5. Clique em Editar autorização na secção Autenticação. É apresentado o painel Autorizar.
  6. Clique em Autorizar.

    Se a autorização for bem-sucedida, o estado da ligação é definido como Ativo na página Ligações.

Entidades, operações e ações

Todos os conetores de integração oferecem uma camada de abstração para os objetos da aplicação ligada. Só pode aceder aos objetos de uma aplicação através desta abstração. A abstração é exposta como entidades, operações e ações.

  • Entidade: pode considerar uma entidade como um objeto ou uma coleção de propriedades na aplicação ou no serviço associado. A definição de uma entidade difere de um conetor para um conetor. Por exemplo, num conetor de base de dados, as tabelas são as entidades. Num conetor de servidor de ficheiros, as pastas são as entidades. Num conetor de sistema de mensagens, as filas são as entidades.

    No entanto, é possível que um conector não suporte ou não tenha entidades, caso em que a lista Entities estará vazia.

  • Operação: uma operação é a atividade que pode realizar numa entidade. Pode realizar qualquer uma das seguintes operações numa entidade:

    Selecionar uma entidade na lista disponível gera uma lista de operações disponíveis para a entidade. Para uma descrição detalhada das operações, consulte as operações de entidades da tarefa de conectores. No entanto, se um conector não suportar nenhuma das operações de entidades, essas operações não suportadas não são apresentadas na lista Operations.

  • Ação: uma ação é uma função de primeira classe que é disponibilizada à integração através da interface do conetor. Uma ação permite-lhe fazer alterações a uma ou mais entidades e varia de conetor para conetor. Normalmente, uma ação tem alguns parâmetros de entrada e um parâmetro de saída. No entanto, é possível que um conector não suporte nenhuma ação, caso em que a lista Actions está vazia.

Limitações do sistema

O conector HTTP pode processar 100 transações por segundo, por nó, e limita todas as transações que excedam este limite. Por predefinição, os Integration Connectors atribuem 2 nós (para uma melhor disponibilidade) a uma ligação.

Para informações sobre os limites aplicáveis aos Integration Connectors, consulte Limites.

Ações suportadas

O conetor HTTP suporta as seguintes ações:

Ação HttpRequest

O conetor HTTP garante, pelo menos, uma tentativa de envio do pedido para o ponto final configurado. Isto está sujeito ao contrato de nível de serviço (SLA) da integração de aplicações. As tabelas seguintes descrevem os parâmetros de entrada e saída da ação HttpRequest.

Parâmetros de entrada da ação HttpRequest

Nome do parâmetro Tipo de dados Obrigatória Descrição
URL Struct Não URL para o qual quer enviar o pedido. O URL tem o formato <scheme>://<netloc>/<path>;<params>?<query>#<fragment>. Se fornecer netloc, substitui o nome do anfitrião fornecido durante a criação da associação.
Método String Não Método de pedido HTTP, como GET, POST, DELETE ou PUT. O valor predefinido é GET.
Cabeçalhos Struct Não Cabeçalhos do pedido HTTP.
Corpo String Não Corpo do pedido HTTP.
RequestHasBytes Booleano Não Se deve enviar o pedido como bytes. Se estiver definido como true, tem de enviar o pedido como uma string codificada em Base64 no parâmetro Body. O valor predefinido é false.
ResponseHasBytes Booleano Não Se deve receber a resposta como bytes. Se estiver definido como true, recebe a resposta como uma string codificada em Base64 no parâmetro de saída ResponseBody. O valor predefinido é false.
HttpVersion String Não Versão HTTP a usar quando faz um pedido. Os valores suportados são 1.1 e 2. Se especificar a versão 2, a negociação ALPN (Application-Layer Protocol Negotiation) é realizada e a versão 1.1 é usada se o servidor não suportar a versão 2. O valor predefinido é 2.
ResponseFormat String Não Especifica o formato da resposta do conetor. Os valores suportados são v1 e v2. O valor predefinido é v1.

Exemplo de resposta da v1:

[{
"ResponseBody": "{\n \"status\": 200\n}"
}, {
"StatusCode": 200.0
}, {
"HttpVersion": "2"
}, {
"ResponseHeaders": {
":status": "200",
"content-length": "19"
}
}]

Exemplo de resposta da v2:

[{
"ResponseBody": "{\n \"status\": 200\n}",
"StatusCode": 200.0,
"HttpVersion": "2",
"ResponseHeaders": {
":status": "200",
"content-length": "19"
}
}]
FailOnError Booleano Não Especifica o comportamento da ligação quando existe um erro na sua aplicação de back-end.
  • true - Aciona uma exceção. A exceção gerada pelo seu back-end é propagada na resposta da ligação.
  • false: não aciona uma exceção. Mas devolve o código de erro e a mensagem de erro na resposta.

O valor predefinido é true.
Tempo limite Número inteiro Não Valor de tempo limite para o pedido HTTP em segundos. O valor máximo permitido é de 150 segundos.

Parâmetros de saída da ação HttpRequest

Nome do parâmetro Tipo de dados Descrição
ResponseBody String Resposta recebida do servidor HTTP.
StatusCode Número inteiro Código de estado recebido do servidor HTTP.
HttpVersion String Versão negociada para o pedido HTTP.
ResponseHeaders Struct Cabeçalhos de resposta HTTP no formato de pares key,value.

Exemplos

Os exemplos nesta secção descrevem as seguintes operações:

  • Configure um payload de pedido
  • Envio de conteúdo de bytes
  • Obtenha conteúdo de bytes

A tabela seguinte lista os cenários de exemplo e a configuração correspondente na tarefa Conectores:

Tarefa Configuração
Configure um payload de pedido
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação HttpRequest e, de seguida, clique em Concluído.
  3. Na secção Entrada da tarefa da tarefa Conectores, clique em connectorInputPayload e, de seguida, introduza um valor semelhante ao seguinte no campo Default Value: 
    {
  "Url": {
    "scheme": "https",
    "netloc": "httpbin.org",
    "path": "post",
    "query": "example=A&sort=value",
    "fragment": "exampleFragment"
  },
  "Method": "POST",
  "Headers": {
    "Accept": ["application/json", "application/xml"],
    "a": "b"
  },
  "Body": "{\"thisIsRequestJSON\":\"someValue\"}"
}
  4. Clique em Guardar.

Este exemplo faz um pedido POST ao URL https://httpbin.org/post?example=A&=value#exampleFragment. Além disso, como netloc é fornecido na carga útil, substitui o nome do anfitrião fornecido durante a criação da ligação.

Envio de conteúdo de bytes

Para enviar conteúdo de bytes (como ficheiros), tem de definir o atributo de pedido RequestHasBytes como true e definir o atributo body como a string codificada em Base64 que quer enviar, conforme mostrado no exemplo seguinte.

  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação HttpRequest e, de seguida, clique em Concluído.
  3. Na secção Entrada da tarefa da tarefa Conectores, clique em connectorInputPayload e, de seguida, introduza um valor semelhante ao seguinte no campo Default Value: 
    {
  "Url": {
    "scheme": "https",
    "netloc": "httpbin.org",
  },
  "Method": "POST",
  "Headers": {
    "Accept": ["application/json", "application/xml"],
    "a": "b"
  },
  "Body": "SGVsbG8gV29ybGQ=",
  "RequestHasBytes":true
}
  4. Clique em Guardar.

Este exemplo faz um pedido POST ao servidor httpbin.org e, no corpo do pedido, envia o conteúdo do ficheiro sob a forma de uma string codificada em Base64. O servidor pode decidir como processar o conteúdo do ficheiro.
Obtenha conteúdo de bytes

Para obter bytes (como uma string Base64) do servidor, tem de definir o atributo de pedido ResponseHasBytes como true, conforme mostrado no exemplo seguinte.

  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação HttpRequest e, de seguida, clique em Concluído.
  3. Na secção Entrada da tarefa da tarefa Conectores, clique em connectorInputPayload e, de seguida, introduza um valor semelhante ao seguinte no campo Default Value: 
    {
  "Url": {
    "scheme": "https",
    "netloc": "httpbin.org",
  },
  "Method": "GET",
  "ResponseHasBytes":true
}
  4. Clique em Guardar.

Este exemplo faz um pedido GET ao servidor httpbin.org e, no corpo do pedido, define ResponseHasBytes como true.
connectorOutputPayload

Códigos de erro

Esta secção descreve as mensagens de erro que pode receber quando usa a ligação HTTP.

Mensagem de erro Causa
Erro ao estabelecer ligação ao servidor HTTP Não foi possível estabelecer ligação HTTP com o servidor devido a uma falha na negociação de SSL ou a um ponto final do servidor HTTP incorreto.
Resposta de erro recebida do servidor HTTP O servidor HTTP ao qual está a tentar estabelecer ligação devolve uma resposta de erro com o código de estado 4xx ou 5xx. Exemplo de resposta: 
{
  "error": {
    "code": 400,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "metadata": {
          "Body": "{\"thisIsResponseJSON\":\"someValue\"}"
          "Error": "Error response received from the HTTP server",
          "Headers": "{\":status\":[\"400\"], \"access-control-allow-credentials\":[\"true\"]}",
          "StatusCode": "400",
          "connection_type": "Http"
        }
      }
    ],
    "message": "Unable to execute HTTP Request",
    "status": "FAILED_PRECONDITION"
  }
}
Erro ao obter o token de acesso Ocorreu um erro ao obter o token de acesso para o tipo de autenticação OAuth Client Credentials Grant.
Erro de autenticação de resumo O tempo de execução do conetor não recebeu um desafio de resumo ou o desafio é de um tipo não suportado.

Crie ligações com o Terraform

Pode usar o recurso do Terraform para criar uma nova associação.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

Para ver um modelo do Terraform de exemplo para a criação de ligações, consulte o modelo de exemplo.

Quando criar esta associação através do Terraform, tem de definir as seguintes variáveis no ficheiro de configuração do Terraform:

Nome do parâmetro Tipo de dados Obrigatória Descrição
proxy_enabled BOOLEAN Falso Selecione esta caixa de verificação para configurar um servidor proxy para a ligação.

Use a ligação HTTP numa integração

Depois de criar a ligação, esta fica disponível no Apigee Integration e no Application Integration. Pode usar a ligação numa integração através da tarefa Conectores.

  • Para compreender como criar e usar a tarefa Connectors no Apigee Integration, consulte o artigo Tarefa Connectors.
  • Para compreender como criar e usar a tarefa Connectors na integração de aplicações, consulte o artigo Tarefa Connectors.

Obtenha ajuda da comunidade do Google Cloud

Pode publicar as suas perguntas e discutir este conector na comunidade do Google Cloud nos Fóruns do Cloud.

O que se segue?