Etapa 2: criar o serviço de proxy (Google Cloud API Gateway) no console

O Snowflake não envia dados (solicitações HTTP POST) diretamente para um serviço remoto. Em vez disso, o Snowflake envia os dados para um serviço de proxy que retransmite os dados do Snowflake para o serviço remoto (por exemplo, GCP Cloud Function) e os transmite de volta.

Este tópico fornece instruções para a criação e configuração de um Google Cloud API Gateway para uso como serviço de proxy para sua função externa.

Neste tópico:

Etapa anterior

Etapa 1: criar o serviço remoto (Google Cloud Function) no Console

Criar uma definição de API

Em seu sistema de arquivo local, crie e personalize um arquivo de configuração com formato YAML que especifique a API que você está criando. O arquivo deve ter a extensão .yaml ou .yml.

Modelo de arquivo de configuração:

swagger: '2.0'
info:
  title: API Gateway config for Snowflake external function.
  description: This configuration file connects the API Gateway resource to the remote service (Cloud Function).
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /<PATH>:
    post:
      summary: Echo the input.
      operationId: echo
      x-google-backend:
        address: <HTTP ENDPOINT TO ROUTE REQUEST TO>
        protocol: h2
      responses:
        '200':
          description: <DESCRIPTION>
          schema:
            type: string
Copy

Preencha ou atualize os seguintes campos:

  1. Substitua <PATH> por um nome único. Isto será incorporado a URLs, portanto, use somente caracteres válidos em URLs. Por exemplo, digite demo-func-resource.

    Observe que, ao contrário dos outros campos neste arquivo de configuração, você deve digitar o valor <PATH> antes dos dois pontos, em vez de depois dos dois pontos. Por exemplo, o seguinte é correto:

    paths:
      /demo-func-resource:
    
    Copy

    O nome do caminho não deve conter parâmetros de caminho. O Google oferece suporte a parâmetros de caminho quando define o caminho para uma URL. Entretanto, o Snowflake não oferece suporte a parâmetros de caminho na URL correspondente especificada na instrução CREATE EXTERNAL FUNCTION.

  2. Copie o caminho (por exemplo, demo-func-resource) da etapa imediatamente anterior para o campo Path Suffix em sua planilha de rastreamento.

  3. Encontre o campo address no campo x-google-backend e substitua <HTTP ENDPOINT TO ROUTE REQUEST TO> pelo valor do campo Cloud Function Trigger URL em sua planilha de rastreamento. O resultado deve ser parecido com:

    x-google-backend:
      address: https:// ...
    
    Copy

    A URL não deve ser colocada entre aspas.

    A URL não precisa ser um ponto de extremidade hospedado pelo Google; ela pode ser o caminho para qualquer ponto de extremidade HTTP.

    Se você selecionou Require HTTPS em Etapa 1: criar o serviço remoto (Google Cloud Function) no Console, então assegure-se de que a URL inserida no campo address comece com https.

  4. Opcionalmente, você pode atualizar qualquer um dos seguintes valores:

    • title na seção info.

    • description na seção info.

    • operationId na subseção post da seção paths.

    • summary na subseção post da seção paths.

  5. Revise seu arquivo de configuração de amostra. Deve ser semelhante ao seguinte:

    swagger: '2.0'
    info:
      title: "API Gateway config for Snowflake external function"
      description: "This configuration file connects the API Gateway resource to the remote service (Cloud Function)."
      version: 1.0.0
    schemes:
      - https
    produces:
      - application/json
    paths:
      /demo-func-resource:
        post:
          summary: "echo the input"
          operationId: echo
          x-google-backend:
            address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
            protocol: h2
          responses:
            '200':
              description: echo result
              schema:
                type: string
    
    Copy

    Nota

    Esta configuração deixará seu gateway aberto ao público até que você o proteja na Etapa 5: criar uma política de segurança do GCP para o serviço de proxy no console deste tutorial.

  6. Opcionalmente, para garantir que ninguém use seu gateway enquanto isso, adicione uma definição de segurança ao arquivo de configuração que usa um nome de conta de serviço temporário e inválido (google_service_account), conforme descrito nesta etapa opcional. Adicionar esta definição de segurança nesta etapa significa que você não pode testar sua função externa até que termine de configurar a segurança em Etapa 5: criar uma política de segurança do GCP para o serviço de proxy no console. Especificamente, a instrução para testar sua função externa em Etapa 4: criar a função externa para o GCP no Snowflake ainda não funcionará.

    1. Adicionar a seguinte seção securityDefinitions imediatamente acima da seção schemes do arquivo de configuração e no mesmo nível de recuo.

      securityDefinitions:
        <security-def-name>:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          x-google-issuer: "google_service_account"
          x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/google_service_account"
      
      Copy
      • Substitua <security-def-name> por um nome de definição de segurança único (por exemplo, snowflakeAccess01).

      • Registre esse nome no campo Security Definition Name da sua planilha de rastreamento.

    2. Atualize a seção post: do arquivo de configuração para fazer referência à definição de segurança que você criou acima. Abaixo do campo operationId, adicione:

      security:
        - <security-def-name>: []
      
      Copy
      • Certifique-se o recuo esteja no mesmo nível que o campo operationId.

      • Substitua <security-def-name> pelo valor do campo Security Definition Name da sua planilha de rastreamento.

      • Certifique-se de incluir um hífen e um espaço em branco antes do nome da definição de segurança, como mostrado acima.

      • Certifique-se de incluir os colchetes vazios ([]) após os dois pontos.

      Por exemplo:

      paths:
        /demo-func-resource:
          post:
            summary: "echo the input"
            operationId: echo
            security:
              - snowflakeAccess01: []
            x-google-backend:
              address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
              protocol: h2
      
      Copy
  7. Salve o arquivo de configuração.

  8. Registre o caminho e o nome do arquivo no campo Configuration File Name da sua planilha de rastreamento.

Para saber mais sobre o arquivo de configuração de API, consulte a seguinte documentação do GCP:

Criar um gateway de API

Para criar um gateway de API:

  1. Crie uma GCP API.

  2. Crie uma configuração de API.

  3. Crie um gateway com a configuração de API.

Criar uma GCP API

Esta etapa cria uma GCP API, que é um recipiente que pode conter um ou mais gateways de API e um ou mais arquivos de configuração:

  1. Se você ainda não fez isso, acesse a tela Google Cloud API Gateway clicando no menu do GCP e selecionando API Gateway.

  2. Clique em CREATE GATEWAY.

  3. Insira o Display Name e a API ID (por exemplo, demo-api-display-name-for-external-function1 e demo-api-id-for-external-function1).

    Você não precisa registrar estes valores em sua planilha de rastreamento porque não precisa inseri-los posteriormente para criar sua função externa. Entretanto, você pode registrar a ID de API para que possa excluí-la quando terminar.

Criar uma configuração de API

Carregue seu arquivo de configuração no console, o que cria uma configuração de API.

  1. Navegue até a seção API Config da tela.

  2. Procure o campo que contém Upload an API Spec.

    Clique em BROWSE e selecione seu arquivo de configuração. O nome de seu arquivo de configuração foi registrado no campo Configuration File Name da sua planilha de rastreamento.

  3. Digite um nome de exibição no campo que contém Display Name.

  4. Selecione uma conta de serviço.

    Se você criou a função de amostra, no campo que contém Select a Service Account, selecione App Engine default service account.

    Se você estiver criando uma função para usar na produção (e não como amostra), você pode escolher uma conta de serviço diferente.

    A conta de serviço selecionada deve ter privilégios apropriados, incluindo privilégios para chamar a Cloud Function.

Criar um gateway com a configuração de API

  1. Navegue até a seção Gateway details da tela.

  2. Digite o Display Name do novo gateway de API.

  3. Clique no campo Location e selecione a região apropriada (por exemplo, us-central1).

  4. Clique em CREATE GATEWAY.

    Isso redireciona você para a tela APIs e mostra uma lista das suas APIs.

    Se sua nova API não estiver visível imediatamente, aguarde alguns minutos e clique no botão Refresh.

  5. Copie o valor do campo Managed Service da API para o campo Managed Service Identifier da sua planilha de rastreamento.

  6. Nesse momento, você ainda deve ver uma lista das suas APIs. Clique no nome da API.

    Você deve ver 4 guias: OVERVIEW, DETAILS, CONFIGS e GATEWAYS.

  7. Clique na guia GATEWAYS.

  8. Copie a Gateway URL para o campo Gateway Base URL da sua planilha de rastreamento.

Próxima etapa

Etapa 3: criar a integração de API para GCP no Snowflake