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 Landessprache übersetzen
  • Supportanfragen aus vielen Sprachen in eine gemeinsame Sprache für Supportfall-Mitarbeiter übersetzen

Ziele

  • Weisen Sie Ihrem Konto die erforderlichen Rollen zu.
  • Cloud Run-Funktion erstellen
  • BigQuery-Dataset erstellen
  • Erstellen Sie eine BigQuery-Verbindung und ein Dienstkonto.
  • 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.

Hinweise

Wir empfehlen, für diese Anleitung ein Google Cloud-Projekt zu erstellen. Außerdem benötigen Sie die erforderlichen Rollen, um diese Anleitung abzuschließen.

Google Cloud-Projekt einrichten

So richten Sie ein Google Cloud-Projekt für diese Anleitung ein:

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

    Enable the 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 auf Projekte, Ordner und Organisationen 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

Wenn Sie die API für Cloud Run-Funktionen aktiviert haben, wurde ein Compute Engine-Standarddienstkonto erstellt. Zum Ausführen dieser Anleitung müssen Sie diesem Standarddienstkonto die Rolle „Cloud Translation API-Nutzer“ zuweisen.

  1. Holen Sie sich die dem Projekt zugewiesene ID.

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

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    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 dann 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 Run-Funktion erstellen

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

  1. Erstellen Sie eine Cloud Run-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 Anfragerate zu steuern, die an die Übersetzung gesendet wird.

    • 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.16.0
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 enthält. Geben Sie beim Erstellen des Datensatzes 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 Run Functions und Cloud Run implementieren können. Wenn Sie eine Verbindung erstellen, wird für diese Verbindung ein Dienstkonto erstellt.

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

    • Wählen Sie als Verbindungstyp die Option BigLake und Remote-Funktionen (Cloud-Ressource) 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 Dienstkonto, das Sie im vorherigen Schritt erstellt haben, benötigt die Berechtigung zur Verwendung von Cloud Run, damit die BigQuery-Remote-Funktion die Cloud Run-Funktion verwenden kann. So gewähren Sie dem Dienstkonto Berechtigungen:

  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 sie aus.

  7. Klicken Sie auf Speichern.

BigQuery-Remote-Funktion erstellen

Gehen Sie folgendermaßen vor, um die Cloud Run-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 zuvor beim Erstellen einer Cloud Run-Funktion gespeichert haben.

  3. Klicken Sie auf Ausführen. Es wird eine Meldung ähnlich der folgenden 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 Run-Funktion verknüpft ist und die erwarteten Ergebnisse auf Spanisch liefert.

  1. Geben Sie die folgende Abfrage in den BigQuery-Abfrageeditor ein und klicken Sie 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: Wenn Sie die Remote-Funktion mit einem öffentlichen Datenpool testen möchten, geben Sie die folgende Abfrage ein und klicken Sie dann auf Ausführen. Verwenden Sie die LIMIT-Klausel, um die Anzahl der 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 in diesem Projekt nicht 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. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Nächste Schritte