Remote-Funktionen und Translation API – Anleitung

In dieser Anleitung wird beschrieben, wie Sie eine BigQuery-Remote-Funktion erstellen, die Cloud Translation API aufrufen und Inhaltsübersetzungen von jeder Sprache ins Spanische mithilfe von SQL und Python durchführen.

Anwendungsfälle für diese Funktion:

  • Nutzerkommentare auf einer Website in eine lokale Sprache übersetzen
  • Supportanfragen aus vielen Sprachen in eine gemeinsame Sprache für Supportfall-Mitarbeiter übersetzen

Lernziele

  • Weisen Sie Ihrem Konto die erforderlichen Rollen zu.
  • Cloud Functions-Funktion erstellen.
  • BigQuery-Dataset erstellen
  • BigQuery-Verbindung und ein Dienstkonto erstellen.
  • Gewähren Sie dem BigQuery-Dienstkonto Berechtigungen.
  • Erstellen Sie eine BigQuery-Remote-Funktion.
  • Rufen Sie die BigQuery-Remote-Funktion auf.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweis

Wir empfehlen Ihnen, für diese Anleitung ein Google Cloud-Projekt zu erstellen. Prüfen Sie außerdem, ob Sie die erforderlichen Rollen für diese Anleitung haben.

Google Cloud-Projekt einrichten

Führen Sie die folgenden Schritte aus, um ein Google Cloud-Projekt für diese Anleitung einzurichten:

  1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  4. BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry und Cloud Run-Administrator APIs aktivieren.

    Aktivieren Sie die APIs

    5.

  5. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  6. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  7. BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry und Cloud Run-Administrator APIs aktivieren.

    Aktivieren Sie die APIs

    8.

Erforderliche Rollen für Ihr Konto

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Aufgaben in dieser Anleitung benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Ausführen der Aufgaben in diesem Dokument erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind für die Aufgaben in dieser Anleitung erforderlich:

  • bigquery.datasets.create
  • bigquery.connections.create
  • bigquery.connections.get
  • cloudfunctions.functions.create

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Erforderliche Rollen für das Compute Engine-Standarddienstkonto

Beim Aktivieren der API für Cloud Functions wurde ein Compute Engine-Standarddienstkonto erstellt. Zum Ausführen dieser Anleitung müssen Sie diesem Standarddienstkonto die Rolle „Cloud Translation API-Nutzer“ zuweisen.

  1. Rufen Sie die dem Projekt zugewiesene ID ab.

  2. Kopieren Sie Ihr Compute Engine-Standarddienstkonto. Ihr Standarddienstkonto sieht so aus:

    PROJECT_NUMBER[email protected]

    Ersetzen Sie PROJECT_NUMBER durch Ihre Projekt-ID.

  3. Öffnen Sie in der Google Cloud Console die Seite IAM.

    IAM aufrufen

  4. Wählen Sie Ihr Projekt aus.

  5. Klicken Sie auf Zugriff gewähren und fügen Sie im Feld Neue Hauptkonten das zuvor kopierte Compute Engine-Standarddienstkonto ein.

  6. Suchen Sie in der Liste Rollen zuweisen nach Cloud Translation API-Nutzer und wählen Sie sie aus.

  7. Klicken Sie auf Speichern.

Cloud Functions-Funktion erstellen

Erstellen Sie mit Cloud Functions eine Funktion, die Eingabetext ins Spanische übersetzt.

  1. Erstellen Sie eine Cloud Functions-Funktion mit den folgenden Spezifikationen:

    • Wählen Sie für Umgebung 2. Generation aus.
    • Geben Sie als Funktionsname translation-handler ein.
    • Wählen Sie als Region die Option us-central1 aus.

    • Geben Sie für Maximale Anzahl von Instanzen den Wert 10 ein.

      Diese Einstellung befindet sich im Abschnitt Laufzeit, Build, Verbindungen und Sicherheitseinstellungen.

      In dieser Anleitung verwenden wir einen niedrigeren Wert als den Standardwert, um die an Translation gesendete Anfragerate zu steuern.

    • Wählen Sie als Laufzeit Python 3.10.

    • Geben Sie als Einstiegspunkt handle_translation ein.

  2. Wählen Sie in der Dateiliste main.py aus und fügen Sie den folgenden Code ein.

    Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

    Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

    from __future__ import annotations

import flask
import functions_framework
from google.api_core.retry import Retry
from google.cloud import translate

# Construct a Translation Client object
translate_client = translate.TranslationServiceClient()

# Register an HTTP function with the Functions Framework
@functions_framework.http
def handle_translation(request: flask.Request) -> flask.Response:
    """BigQuery remote function to translate input text.

    Args:
        request: HTTP request from BigQuery
        https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#input_format

    Returns:
        HTTP response to BigQuery
        https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#output_format
    """
    try:
        # Parse request data as JSON
        request_json = request.get_json()
        # Get the project of the query
        caller = request_json["caller"]
        project = extract_project_from_caller(caller)
        if project is None:
            return flask.make_response(
                flask.jsonify(
                    {
                        "errorMessage": (
                            'project can\'t be extracted from "caller":' f" {caller}."
                        )
                    }
                ),
                400,
            )
        # Get the target language code, default is Spanish ("es")
        context = request_json.get("userDefinedContext", {})
        target = context.get("target_language", "es")

        calls = request_json["calls"]
        translated = translate_text([call[0] for call in calls], project, target)

        return flask.jsonify({"replies": translated})
    except Exception as err:
        return flask.make_response(
            flask.jsonify({"errorMessage": f"Unexpected error {type(err)}:{err}"}),
            400,
        )

def extract_project_from_caller(job: str) -> str:
    """Extract project id from full resource name of a BigQuery job.

    Args:
        job: full resource name of a BigQuery job, like
          "//bigquery.googleapi.com/projects/<project>/jobs/<job_id>"

    Returns:
        project id which is contained in the full resource name of the job.
    """
    path = job.split("/")
    return path[4] if len(path) > 4 else None

def translate_text(
    calls: list[str], project: str, target_language_code: str
) -> list[str]:
    """Translates the input text to specified language using Translation API.

    Args:
        calls: a list of input text to translate.
        project: the project where the translate service will be used.
        target_language_code: The ISO-639 language code to use for translation
          of the input text. See
          https://cloud.google.com/translate/docs/advanced/discovering-supported-languages-v3#supported-target
            for the supported language list.

    Returns:
        a list of translated text.
    """
    location = "<your location>"
    parent = f"projects/{project}/locations/{location}"
    # Call the Translation API, passing a list of values and the target language
    response = translate_client.translate_text(
        request={
            "parent": parent,
            "contents": calls,
            "target_language_code": target_language_code,
            "mime_type": "text/plain",
        },
        retry=Retry(),
    )
    # Convert the translated value to a list and return it
    return [translation.translated_text for translation in response.translations]

    Aktualisieren <your location> mit us-central1.

  3. Wählen Sie in der Dateiliste requirements.txt aus und fügen Sie den folgenden Text ein:

    Flask==2.2.2
functions-framework==3.5.0
google-cloud-translate==3.11.1
Werkzeug==2.3.7

  4. Klicken Sie auf Bereitstellen und warten Sie, bis die Funktion bereitgestellt wurde.

  5. Klicken Sie auf den Tab Trigger.

  6. Kopieren Sie den Wert für die Trigger-URL und speichern Sie ihn für später. Sie müssen diese URL verwenden, wenn Sie eine BigQuery-Remote-Funktion erstellen.

Erstellen Sie ein BigQuery-Dataset

Erstellen Sie ein BigQuery-Dataset, das die Remote-Funktion enthalten soll. Geben Sie beim Erstellen des Datasets die folgenden Spezifikationen an:

  • Geben Sie unter Dataset-ID remote_function_test ein.
  • Wählen Sie unter Standorttyp die Option Mehrere Regionen aus.
  • Wählen Sie für Mehrere Regionen die Option US (mehrere Regionen in den USA) aus.

BigQuery-Verbindung und -Dienstkonto erstellen

Erstellen Sie eine BigQuery-Verbindung, damit Sie eine Remote-Funktion mit allen unterstützten Sprachen in Cloud Functions und Cloud Run implementieren können. Wenn Sie eine Verbindung herstellen, wird ein Dienstkonto für diese Verbindung erstellt.

  1. Erstellen Sie eine Google Cloud-Ressourcenverbindung mit den folgenden Spezifikationen:

    • Wählen Sie als Verbindungstyp die Option BigLake und Remotefunktionen (Cloud Resource) aus.
    • Geben Sie als Verbindungs-ID remote-function-connection ein.
    • Wählen Sie unter Standorttyp die Option Mehrere Regionen aus.
    • Wählen Sie für Mehrere Regionen die Option US (mehrere Regionen in den USA) aus.

  2. Öffnen Sie die Liste Externe Verbindungen und wählen Sie us.remote-function-connection aus.

  3. Kopieren Sie die Dienstkonto-ID und speichern Sie sie für später. Sie müssen dieser ID im nächsten Schritt Berechtigungen erteilen.

Berechtigungen für das BigQuery-Dienstkonto gewähren

Das im vorherigen Schritt erstellte Dienstkonto benötigt die Berechtigung zur Verwendung von Cloud Run, damit die BigQuery-Remote-Funktion die Cloud Functions-Funktion verwenden kann. Führen Sie die folgenden Schritte aus, um dem Dienstkonto Berechtigungen zu erteilen:

  1. Zur Seite „Cloud Run“

    Öffnen Sie Cloud Run.

  2. Wählen Sie Ihr Projekt aus.

  3. Klicken Sie das Kästchen neben translation-handler an.

  4. Klicken Sie im Bereich Berechtigungen auf Hauptkonto hinzufügen.

  5. Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID ein, die Sie zuvor kopiert haben.

  6. Suchen Sie in der Liste Rollen zuweisen nach Cloud Run Invoker und wählen Sie es aus.

  7. Klicken Sie auf Speichern.

BigQuery-Remote-Funktion erstellen

Gehen Sie folgendermaßen vor, um die Cloud Functions-Funktion, die Text ins Spanische übersetzt, mit einer BigQuery-Remote-Funktion zu verwenden.

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Abfrage ein:

    CREATE OR REPLACE FUNCTION `remote_function_test.translate_text`(x STRING)
RETURNS
STRING
    REMOTE WITH CONNECTION `us.remote-function-connection`
OPTIONS (
    endpoint = 'TRIGGER_URL',
    max_batching_rows = 10);

    Ersetzen Sie TRIGGER_URL durch die Trigger-URL, die Sie beim Erstellen einer Cloud Functions-Funktion zuvor gespeichert haben.

  3. Klicken Sie auf Ausführen. Eine Meldung ähnlich der folgenden wird angezeigt:

    This statement created a new function named
your_project.remote_function_test.translate_text.

BigQuery-Remote-Funktion aufrufen

Nachdem Sie Ihre Remote-Funktion erstellt haben, testen Sie sie, damit sichergestellt ist, dass sie mit der Cloud Functions-Funktion verknüpft ist und die erwarteten Ergebnisse auf Spanisch liefert.

  1. Geben Sie im BigQuery-Abfrageeditor die folgende Abfrage ein und klicken Sie dann auf Ausführen.

    SELECT
  remote_function_test.translate_text('This new feature is fantastic!')
    AS translated_text;

    Die Richtlinien sehen in etwa so aus:

    +-------------------------------------------+
| translated_text                           |
+-------------------------------------------+
| ¡Esta nueva característica es fantástica! |
+-------------------------------------------+

  2. Optional: Geben Sie die folgende Abfrage ein und klicken Sie auf Ausführen, um die Remote-Funktion für ein öffentliches Dataset zu testen. Verwenden Sie die Klausel LIMIT, um die zurückgegebenen Ergebnisse zu begrenzen.

    SELECT
    text,
    remote_function_test.translate_text(text) AS translated_text
FROM
    (SELECT text FROM `bigquery-public-data.hacker_news.full` LIMIT 3);

    Die Richtlinien sehen in etwa so aus:

    +---------------------------------------------------------------------------+
| text                            | translated_text                         |
+---------------------------------------------------------------------------+
| These benchmarks look good.     | Estos puntos de referencia se ven bien. |
| Who is using Java?              | ¿Quién está usando Java?                |
| You need more database storage. | Necesitas más almacenamiento.           |
+---------------------------------------------------------------------------+

Ressourcen löschen

Wenn Sie diese Funktionen nicht in diesem Projekt verwenden möchten, können Sie zusätzliche Kosten vermeiden, indem Sie das Projekt löschen. Dadurch werden alle mit dem Projekt verknüpften Ressourcen endgültig gelöscht.

  1. Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.

    Zur Seite „Ressourcen verwalten“

  2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen.
  3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Beenden), um das Projekt zu löschen.

Nächste Schritte