Trabalhe com funções remotas

Uma função remota do BigQuery permite-lhe implementar a sua função noutros idiomas que não SQL e Javascript ou com as bibliotecas ou os serviços que não são permitidos nas funções definidas pelo utilizador do BigQuery.

Vista geral

Uma função remota do BigQuery permite-lhe incorporar a funcionalidade do GoogleSQL com software fora do BigQuery, fornecendo uma integração direta com as funções do Cloud Run e o Cloud Run. Com as funções remotas do BigQuery, pode implementar as suas funções nas funções do Cloud Run ou no Cloud Run implementado com qualquer idioma suportado e, em seguida, invocá-las a partir de consultas GoogleSQL.

Fluxo de trabalho

1. Crie o ponto final HTTP nas funções do Cloud Run ou no Cloud Run.
2. Crie uma função remota no BigQuery.
   1. Crie uma associação do tipo CLOUD_RESOURCE.
   2. Crie uma função remota.
3. Use a função remota numa consulta tal como qualquer outra função definida pelo utilizador.

Limitações

• As funções remotas só suportam um dos seguintes tipos de dados como tipo de argumento ou tipo de retorno:

  • Booleano
  • Bytes
  • Numérico
  • String
  • Data
  • Data/hora
  • Hora
  • Indicação de tempo
  • JSON

  As funções remotas não suportam os tipos ARRAY, STRUCT, INTERVAL nem GEOGRAPHY.

• Não pode criar funções remotas de valor de tabela.

• Não pode usar funções remotas quando cria vistas materializadas.

• O valor de devolução de uma função remota é sempre considerado não determinístico, pelo que o resultado de uma consulta que chama uma função remota não é colocado em cache.

• Pode ver pedidos repetidos com os mesmos dados para o seu ponto final, mesmo após respostas bem-sucedidas, devido a erros de rede temporários ou erros internos do BigQuery.

• Quando uma avaliação de função remota é ignorada para algumas linhas devido à interrupção, por exemplo, em expressões condicionais ou uma declaração MERGE com WHEN [NOT] MATCHED, o processamento em lote não é usado com a função remota. Neste caso, o campo calls no corpo do pedido HTTP tem exatamente um elemento.

• Se o conjunto de dados associado à função remota for replicado para uma região de destino através da replicação de conjuntos de dados entre regiões, só é possível consultar a função remota na região em que foi criada.

Crie um ponto final

Para criar uma função remota que possa implementar lógica empresarial, tem de criar um endpoint HTTP através das funções do Cloud Run ou do Cloud Run. O ponto final tem de conseguir processar um lote de linhas num único pedido HTTP POST e devolver os resultados do lote como uma resposta HTTP.

Se estiver a criar a função remota através de BigQuery DataFrames, não tem de criar manualmente o ponto final HTTP. O serviço faz isso automaticamente.

Consulte o tutorial sobre as funções do Cloud Run e outra documentação sobre as funções do Cloud Run para saber como escrever, implementar, testar e manter uma função do Cloud Run.

Consulte o início rápido do Cloud Run e outra documentação do Cloud Run sobre como escrever, implementar, testar e manter um serviço do Cloud Run.

Recomendamos que mantenha a autenticação predefinida em vez de permitir a invocação não autenticada da sua função do Cloud Run ou serviço do Cloud Run.

Formato de entrada

O BigQuery envia pedidos HTTP POST com o corpo JSON no seguinte formato:

Exemplo de um pedido:

{
 "requestId": "124ab1c",
 "caller": "//bigquery.googleapis.com/projects/myproject/jobs/myproject:US.bquxjob_5b4c112c_17961fafeaf",
 "sessionUser": "test-user@test-company.com",
 "userDefinedContext": {
  "key1": "value1",
  "key2": "v2"
 },
 "calls": [
  [null, 1, "", "abc"],
  ["abc", "9007199254740993", null, null]
 ]
}

Formato de saída

O BigQuery espera que o ponto final devolva uma resposta HTTP no seguinte formato. Caso contrário, o BigQuery não a pode consumir e a consulta que chama a função remota falha.

Um exemplo de uma resposta bem-sucedida:

{
  "replies": [
    1,
    0
  ]
}

Um exemplo de uma resposta com falha:

{
  "errorMessage": "Received but not expected that the argument 0 be null".
}

Código de resposta HTTP

O seu ponto final deve devolver o código de resposta HTTP 200 para uma resposta bem-sucedida. Quando o BigQuery recebe qualquer outro valor, considera a resposta como uma falha e tenta novamente quando o código de resposta HTTP é 408, 429, 500, 503 ou 504 até atingir um limite interno.

Codificação JSON do tipo de dados SQL

A codificação JSON no pedido/resposta HTTP segue a codificação JSON do BigQuery existente para a função TO_JSON_STRING.

Exemplo de código de função do Cloud Run

O seguinte exemplo de código Python implementa a adição de todos os argumentos inteiros da função remota. Processa um pedido com os argumentos para invocações em lote e devolve todos os resultados numa resposta.

import functions_framework

from flask import jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992

@functions_framework.http
def batch_add(request):
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return_json = jsonify( { "replies":  replies } )
    return return_json
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

Partindo do princípio de que a função está implementada no projeto my_gcf_project na região us-east1 com o nome da função remote_add, pode aceder-lhe através do ponto final https://us-east1-my_gcf_project.cloudfunctions.net/remote_add.

Exemplo de código do Cloud Run

O seguinte exemplo de código Python implementa um serviço Web que pode ser criado e implementado no Cloud Run para a mesma funcionalidade.

import os

from flask import Flask, request, jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992

app = Flask(__name__)

@app.route("/", methods=['POST'])
def batch_add():
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return jsonify( { "replies" :  replies } )
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

Consulte o guia sobre como criar e implementar o código.

Partindo do princípio de que o serviço do Cloud Run está implementado no projeto my_gcf_project na região us-east1 com o nome do serviço remote_add, pode aceder-lhe através do ponto final https://remote_add-<project_id_hash>-ue.a.run.app.

Crie uma função remota

O BigQuery usa uma ligação CLOUD_RESOURCE para interagir com a sua função do Cloud Run. Para criar uma função remota, tem de criar uma associação CLOUD_RESOURCE. Se estiver a criar a função remota através dos DataFrames do BigQuery e lhe tiver sido concedida a função de administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin), não tem de criar manualmente a ligação nem conceder-lhe acesso. O serviço faz isso automaticamente por si.

Crie uma associação

Tem de ter uma ligação de recursos da nuvem para se ligar à função do Cloud Run e ao Cloud Run.

Pode ignorar este passo se tiver uma associação predefinida configurada ou tiver a função de administrador do BigQuery.

Crie uma ligação de recursos da nuvem para o modelo remoto usar e obtenha a conta de serviço da ligação. Crie a associação na mesma localização que o conjunto de dados que criou no passo anterior.

Selecione uma das seguintes opções:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Configure o acesso

Tem de conceder à nova associação acesso só de leitura à sua função do Cloud Run ou serviço do Cloud Run. Não recomendamos que permita a invocação não autenticada para a sua função do Cloud Run ou serviço do Cloud Run.

Para conceder funções, siga estes passos:

1. Aceda à página IAM e administrador.

   Aceda a IAM e administração

2. Clique em person_add Adicionar.

   É apresentada a caixa de diálogo Adicionar responsáveis.

3. No campo Novos membros, introduza o ID da conta de serviço que copiou anteriormente.

4. No campo Selecionar uma função, selecione uma das seguintes opções:

   • Se estiver a usar uma função do Cloud Run de 1.ª geração, escolha Função do Cloud e, de seguida, selecione Função do invocador da função do Cloud.
   • Se estiver a usar uma função do Cloud Run de 2.ª geração, escolha Cloud Run e, de seguida, selecione Função de invocador do Cloud Run.
   • Se estiver a usar um serviço do Cloud Run, escolha Cloud Run e, de seguida, selecione Função de invocador do Cloud Run.

5. Clique em Guardar.

Crie uma função remota

Para criar uma função remota:

Tem de ter a autorização bigquery.routines.create no conjunto de dados onde cria a função remota e a autorização bigquery.connections.delegate (disponível na função de administrador da ligação do BigQuery) na ligação usada pela função remota.

Disponibilizar contexto definido pelo utilizador

Pode especificar user_defined_context em OPTIONS como uma forma de pares de chave-valor, que farão parte de cada pedido HTTP ao ponto final. Com o contexto definido pelo utilizador, pode criar várias funções remotas, mas reutilizar um único ponto final, que oferece comportamentos diferentes com base no contexto que lhe é transmitido.

Os exemplos seguintes criam duas funções remotas para encriptar e desencriptar BYTES dados através do mesmo ponto final.

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.encrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "encryption")]
)

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.decrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "decryption")]
)

Limitar o número de linhas num pedido em lote

Pode especificar max_batching_rows em OPTIONS como o número máximo de linhas em cada pedido HTTP para evitar o tempo limite das funções do Cloud Run. Se especificar max_batching_rows, o BigQuery determina o número de linhas num lote até ao limite de max_batching_rows. Se não for especificado, o BigQuery determina automaticamente o número de linhas a processar em lote.

Use uma função remota numa consulta

Certifique-se de que concedeu a autorização na sua função do Cloud Run, para que seja acessível à conta de serviço do BigQuery associada à ligação da função remota.

Também tem de ter a autorização bigquery.routines.get no conjunto de dados onde se encontra a função remota e a autorização bigquery.connections.use, que pode obter através da função BigQuery Connection User na ligação usada pela função remota.

Pode usar uma função remota numa consulta tal como uma função definida pelo utilizador.

Por exemplo, pode usar a função remote_add na consulta de exemplo:

SELECT
  val,
  `PROJECT_ID.DATASET_ID`.remote_add(val, 2)
FROM
  UNNEST([NULL,2,3,5,8]) AS val;

Este exemplo produz o seguinte resultado:

+------+-----+
|  val | f0_ |
+------+-----+
| NULL |   2 |
|    2 |   4 |
|    3 |   5 |
|    5 |   7 |
|    8 |  10 |
+------+-----+

Regiões suportadas

Existem dois tipos de localizações no BigQuery:

• Uma região é um local geográfico específico, como Londres.

• Uma multirregião é uma grande área geográfica, como os Estados Unidos, que contém dois ou mais locais geográficos.

Regiões únicas

Num conjunto de dados de região única do BigQuery, só pode criar uma função remota que use uma função do Cloud Run implementada na mesma região. Por exemplo:

• Uma função remota na região única do BigQuery us-east4 só pode usar uma função do Cloud Run em us-east4.

Assim, para regiões únicas, as funções remotas só são suportadas em regiões que suportam funções do Cloud Run e o BigQuery.

Várias regiões

Num conjunto de dados multirregião do BigQuery (US, EU), só pode criar uma função remota que use uma função do Cloud Run implementada numa região na mesma grande área geográfica (EUA, UE). Por exemplo:

• Uma função remota na multirregião do BigQuery US só pode usar uma função do Cloud Run implementada numa única região na área geográfica dos EUA, como us-central1, us-east4, us-west2, etc.
• Uma função remota na EUmultirregião do BigQuery só pode usar uma função do Cloud Run implementada numa única região nos estados-membros da União Europeia, como europe-north1, europe-west3, etc.

Para mais informações acerca das regiões e das multirregiões do BigQuery, consulte a página Localizações de conjuntos de dados. Para mais informações sobre as regiões das funções do Cloud Run, consulte a página Localizações das funções do Cloud Run.

Ligações

Para uma localização de região única ou de várias regiões, só pode criar uma função remota na mesma localização que a ligação que usa. Por exemplo, para criar uma função remota na região US, use uma ligação localizada na região US.

Preços

• Aplicam-se os preços do BigQuery padrão.

• Além disso, podem ser incorridos custos para as funções do Cloud Run e o Cloud Run ao usar esta funcionalidade. Reveja as páginas de preços das funções do Cloud Run e do Cloud Run para ver detalhes.

Usar os VPC Service Controls

O VPC Service Controls é uma Trusted Cloud by S3NS funcionalidade que lhe permite configurar um perímetro seguro para se proteger contra a exfiltração de dados. Para usar os VPC Service Controls com funções remotas para segurança adicional ou usar endpoints com internal traffic definições de entrada, siga o guia dos VPC Service Controls para:

1. Crie um perímetro de serviço.

2. Adicione o projeto do BigQuery da consulta que usa a função remota ao perímetro.

3. Adicione o projeto do ponto final ao perímetro e defina Cloud Functions API ou Cloud Run API nos serviços restritos com base no tipo de ponto final. Para mais detalhes, consulte os artigos VPC Service Controls das funções do Cloud Run e VPC Service Controls do Cloud Run.

Práticas recomendadas para funções remotas

• Pré-filtrar a entrada: se a entrada puder ser facilmente filtrada antes de ser transmitida a uma função remota, a consulta tem provavelmente um processamento mais rápido e é mais barata.

• Mantenha a sua função do Cloud Run escalável. A escalabilidade é uma função de instâncias mínimas, instâncias máximas e concorrência.

  • Sempre que possível, use o valor predefinido para o número máximo de instâncias da função do Cloud Run.
  • Tenha em atenção que não existe um limite predefinido para as funções HTTP do Cloud Run de 1.ª geração. Para evitar eventos de escalabilidade ilimitados com funções HTTP do Cloud Run de 1.ª geração durante os testes ou em produção, recomendamos que defina um limite, por exemplo, 3000.

• Siga outras sugestões de funções do Cloud Run para um melhor desempenho. As consultas de funções remotas que interagem com uma função do Cloud Run de latência elevada podem falhar devido ao limite de tempo.

• Implemente o seu ponto final para devolver um código de resposta HTTP e um payload corretos para uma resposta com falha.

  • Para minimizar as novas tentativas do BigQuery, use códigos de resposta HTTP que não sejam 408, 429, 500, 503 e 504 para uma resposta com falha e certifique-se de que captura todas as exceções no código da função. Caso contrário, a estrutura do serviço HTTP pode devolver automaticamente 500 para quaisquer exceções não capturadas. Pode continuar a ver pedidos HTTP repetidos quando o BigQuery repete uma partição de dados ou uma consulta com falhas.

  • O seu ponto final deve devolver um payload JSON no formato definido para uma resposta com falha. Embora não seja estritamente necessário, ajuda o BigQuery a distinguir se a resposta com falha é da implementação da sua função ou da infraestrutura das funções do Cloud Run/Cloud Run. No caso da segunda opção, o BigQuery pode tentar novamente com um limite interno diferente.

Quotas

Para ver informações sobre as quotas de funções remotas, consulte o artigo Quotas e limites.