光學字元辨識 (OCR) 教學課程 (第 1 代)

瞭解如何在 Google Cloud中執行光學字元辨識 (OCR)。本教學課程示範如何將圖片檔上傳至 Cloud Storage、使用 Cloud Vision API 從圖片中擷取文字、透過 Google Cloud Translation API 翻譯文字，以及將翻譯內容存回 Cloud Storage。Pub/Sub 可將各項工作排入佇列，並觸發正確的 Cloud Run functions 以執行工作。

如要進一步瞭解如何傳送文字偵測 (OCR) 要求，請參閱「偵測圖片中的文字」、「偵測圖片中的手寫內容」或「偵測檔案中的文字 (PDF/TIFF)」。

目標

• 編寫及部署數個背景 Cloud Run functions。
• 將圖片上傳至 Cloud Storage。
• 擷取、翻譯及儲存包含在上傳圖片中的文字。

費用

在本文件中，您會使用下列 Google Cloud的計費元件：

• Cloud Run functions
• Pub/Sub
• Cloud Storage
• Cloud Translation API
• Cloud Vision

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions, Cloud Build, Cloud Pub/Sub, Cloud Storage, Cloud Translation, and Cloud Vision APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions, Cloud Build, Cloud Pub/Sub, Cloud Storage, Cloud Translation, and Cloud Vision APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

如已安裝 gcloud CLI，請執行下列指令進行更新：

gcloud components update

1. 準備開發環境。

   Node.js

   前往 Node.js 設定指南

   Python

   前往 Python 設定指南

   Go

   前往 Go 設定指南

   Java

   前往 Java 設定指南

以圖表呈現資料流程

OCR 教學課程應用程式中的資料流程包含以下幾個步驟：

1. 將包含任何語言文字的圖片上傳至 Cloud Storage。
2. 觸發 Cloud Run 函式，使用 Vision API 擷取文字並偵測原文語言。
3. 將訊息發布至 Pub/Sub 主題，藉此將文字排入翻譯佇列。系統會為每個與原文語言不同的譯文語言建立翻譯佇列。
4. 如果譯文語言與原文語言相符，則會略過翻譯佇列，並將文字直接傳送至結果佇列，也就是另一個 Pub/Sub 主題。
5. Cloud Run 函式會使用 Translation API 譯出翻譯佇列中的文字。翻譯結果會傳送至結果佇列。
6. 另一個 Cloud Run 函式會將結果佇列中的翻譯文字儲存至 Cloud Storage。
7. 翻譯結果會以文字檔案的形式儲存在 Cloud Storage 中，每份翻譯各有一個檔案。

以下可能有助於透過圖表呈現的方式瞭解步驟：

準備應用程式

1. 建立用來上傳圖片的 Cloud Storage bucket，其中 YOUR_IMAGE_BUCKET_NAME 是全域不重複的 bucket 名稱：

   gcloud storage buckets create gs://YOUR_IMAGE_BUCKET_NAME

2. 建立用來儲存文字翻譯的 Cloud Storage bucket，其中 YOUR_RESULT_BUCKET_NAME 是全域不重複的 bucket 名稱：

   gcloud storage buckets create gs://YOUR_RESULT_BUCKET_NAME

3. 建立用來發布翻譯要求的 Pub/Sub 主題，其中 YOUR_TRANSLATE_TOPIC_NAME 是翻譯要求主題的名稱：

   gcloud pubsub topics create YOUR_TRANSLATE_TOPIC_NAME

4. 建立 Pub/Sub 主題，將翻譯完成的結果發布至該主題，其中 YOUR_RESULT_TOPIC_NAME 是翻譯結果主題的名稱：

   gcloud pubsub topics create YOUR_RESULT_TOPIC_NAME

5. 將應用程式存放區範例複製到本機電腦中：

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   您也可以下載 zip 格式的範例檔案，然後將檔案解壓縮。

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   您也可以下載 zip 格式的範例檔案，然後將檔案解壓縮。

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   您也可以下載 zip 格式的範例檔案，然後將檔案解壓縮。

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   您也可以下載 zip 格式的範例檔案，然後將檔案解壓縮。

6. 變更為包含 Cloud Run 函式程式碼範例的目錄：

   Node.js

   cd nodejs-docs-samples/functions/ocr/app/

   Python

   cd python-docs-samples/functions/ocr/app/

   Go

   cd golang-samples/functions/ocr/app/

   Java

   cd java-docs-samples/functions/ocr/ocr-process-image/

瞭解程式碼

匯入依附元件

應用程式必須匯入數個依附元件，才能與 Google Cloud Platform 服務通訊：

Node.js

// Get a reference to the Pub/Sub component
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
// Get a reference to the Cloud Storage component
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();

// Get a reference to the Cloud Vision API component
const Vision = require('@google-cloud/vision');
const vision = new Vision.ImageAnnotatorClient();

// Get a reference to the Translate API component
const {Translate} = require('@google-cloud/translate').v2;
const translate = new Translate();

Python

import base64
import json
import os
from typing import Dict, TypeVar

from google.cloud import pubsub_v1
from google.cloud import storage
from google.cloud import translate_v2 as translate
from google.cloud import vision

vision_client = vision.ImageAnnotatorClient()
translate_client = translate.Client()
publisher = pubsub_v1.PublisherClient()
storage_client = storage.Client()

project_id = os.environ["GCP_PROJECT"]

Go

// Package ocr contains Go samples for creating OCR
// (Optical Character Recognition) Cloud functions.
package ocr

import (
	"context"
	"fmt"
	"os"
	"strings"
	"time"

	"cloud.google.com/go/pubsub"
	"cloud.google.com/go/storage"
	"cloud.google.com/go/translate"
	vision "cloud.google.com/go/vision/apiv1"
	"golang.org/x/text/language"
)

type ocrMessage struct {
	Text     string       `json:"text"`
	FileName string       `json:"fileName"`
	Lang     language.Tag `json:"lang"`
	SrcLang  language.Tag `json:"srcLang"`
}

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Bucket         string    `json:"bucket"`
	Name           string    `json:"name"`
	Metageneration string    `json:"metageneration"`
	ResourceState  string    `json:"resourceState"`
	TimeCreated    time.Time `json:"timeCreated"`
	Updated        time.Time `json:"updated"`
}

// PubSubMessage is the payload of a Pub/Sub event.
// See the documentation for more details:
// https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
type PubSubMessage struct {
	Data []byte `json:"data"`
}

var (
	visionClient    *vision.ImageAnnotatorClient
	translateClient *translate.Client
	pubsubClient    *pubsub.Client
	storageClient   *storage.Client

	projectID      string
	resultBucket   string
	resultTopic    string
	toLang         []string
	translateTopic string
)

func setup(ctx context.Context) error {
	projectID = os.Getenv("GCP_PROJECT")
	resultBucket = os.Getenv("RESULT_BUCKET")
	resultTopic = os.Getenv("RESULT_TOPIC")
	toLang = strings.Split(os.Getenv("TO_LANG"), ",")
	translateTopic = os.Getenv("TRANSLATE_TOPIC")

	var err error // Prevent shadowing clients with :=.

	if visionClient == nil {
		visionClient, err = vision.NewImageAnnotatorClient(ctx)
		if err != nil {
			return fmt.Errorf("vision.NewImageAnnotatorClient: %w", err)
		}
	}

	if translateClient == nil {
		translateClient, err = translate.NewClient(ctx)
		if err != nil {
			return fmt.Errorf("translate.NewClient: %w", err)
		}
	}

	if pubsubClient == nil {
		pubsubClient, err = pubsub.NewClient(ctx, projectID)
		if err != nil {
			return fmt.Errorf("translate.NewClient: %w", err)
		}
	}

	if storageClient == nil {
		storageClient, err = storage.NewClient(ctx)
		if err != nil {
			return fmt.Errorf("storage.NewClient: %w", err)
		}
	}
	return nil
}

Java

public class OcrProcessImage implements BackgroundFunction<GcsEvent> {
  // TODO<developer> set these environment variables
  private static final String PROJECT_ID = System.getenv("GCP_PROJECT");
  private static final String TRANSLATE_TOPIC_NAME = System.getenv("TRANSLATE_TOPIC");
  private static final String[] TO_LANGS = System.getenv("TO_LANG").split(",");

  private static final Logger logger = Logger.getLogger(OcrProcessImage.class.getName());
  private static final String LOCATION_NAME = LocationName.of(PROJECT_ID, "global").toString();
  private Publisher publisher;

  public OcrProcessImage() throws IOException {
    publisher = Publisher.newBuilder(
        ProjectTopicName.of(PROJECT_ID, TRANSLATE_TOPIC_NAME)).build();
  }
}

處理圖片

下列函式會從 Cloud Storage 中讀取上傳的圖片檔案，並呼叫函式來偵測圖片中是否包含文字：

Node.js

/**
 * This function is exported by index.js, and is executed when
 * a file is uploaded to the Cloud Storage bucket you created
 * for uploading images.
 *
 * @param {object} event A Google Cloud Storage File object.
 */
exports.processImage = async event => {
  const {bucket, name} = event;

  if (!bucket) {
    throw new Error(
      'Bucket not provided. Make sure you have a "bucket" property in your request'
    );
  }
  if (!name) {
    throw new Error(
      'Filename not provided. Make sure you have a "name" property in your request'
    );
  }

  await detectText(bucket, name);
  console.log(`File ${name} processed.`);
};

Python

def process_image(file_info: dict, context: dict) -> None:
    """Cloud Function triggered by Cloud Storage when a file is changed.

    Args:
        file_info: Metadata of the changed file, provided by the
            triggering Cloud Storage event.
        context: a dictionary containing metadata about the event.

    Returns:
        None; the output is written to stdout and Cloud Logging.
    """
    bucket = validate_message(file_info, "bucket")
    name = validate_message(file_info, "name")

    detect_text(bucket, name)

    print(f"File '{file_info['name']}' processed.")

Go

package ocr

import (
	"context"
	"fmt"
	"log"
)

// ProcessImage is executed when a file is uploaded to the Cloud Storage bucket you
// created for uploading images. It runs detectText, which processes the image for text.
func ProcessImage(ctx context.Context, event GCSEvent) error {
	if err := setup(ctx); err != nil {
		return fmt.Errorf("ProcessImage: %w", err)
	}
	if event.Bucket == "" {
		return fmt.Errorf("empty file.Bucket")
	}
	if event.Name == "" {
		return fmt.Errorf("empty file.Name")
	}
	if err := detectText(ctx, event.Bucket, event.Name); err != nil {
		return fmt.Errorf("detectText: %w", err)
	}
	log.Printf("File %s processed.", event.Name)
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import com.google.cloud.pubsub.v1.Publisher;
import com.google.cloud.translate.v3.DetectLanguageRequest;
import com.google.cloud.translate.v3.DetectLanguageResponse;
import com.google.cloud.translate.v3.LocationName;
import com.google.cloud.translate.v3.TranslationServiceClient;
import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.cloud.vision.v1.ImageSource;
import com.google.protobuf.ByteString;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.PubsubMessage;
import functions.eventpojos.GcsEvent;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.logging.Level;
import java.util.logging.Logger;

  @Override
  public void accept(GcsEvent gcsEvent, Context context) {

    // Validate parameters
    String bucket = gcsEvent.getBucket();
    if (bucket == null) {
      throw new IllegalArgumentException("Missing bucket parameter");
    }
    String filename = gcsEvent.getName();
    if (filename == null) {
      throw new IllegalArgumentException("Missing name parameter");
    }

    detectText(bucket, filename);
  }
}

下列函式會使用 Vision API 從圖片中擷取文字，並將文字排入翻譯佇列中：

Node.js

/**
 * Detects the text in an image using the Google Vision API.
 *
 * @param {string} bucketName Cloud Storage bucket name.
 * @param {string} filename Cloud Storage file name.
 * @returns {Promise}
 */
const detectText = async (bucketName, filename) => {
  console.log(`Looking for text in image ${filename}`);
  const [textDetections] = await vision.textDetection(
    `gs://${bucketName}/${filename}`
  );
  const [annotation] = textDetections.textAnnotations;
  const text = annotation ? annotation.description.trim() : '';
  console.log('Extracted text from image:', text);

  let [translateDetection] = await translate.detect(text);
  if (Array.isArray(translateDetection)) {
    [translateDetection] = translateDetection;
  }
  console.log(
    `Detected language "${translateDetection.language}" for ${filename}`
  );

  // Submit a message to the bus for each language we're going to translate to
  const TO_LANGS = process.env.TO_LANG.split(',');
  const topicName = process.env.TRANSLATE_TOPIC;

  const tasks = TO_LANGS.map(lang => {
    const messageData = {
      text: text,
      filename: filename,
      lang: lang,
    };

    // Helper function that publishes translation result to a Pub/Sub topic
    // For more information on publishing Pub/Sub messages, see this page:
    //   https://cloud.google.com/pubsub/docs/publisher
    return publishResult(topicName, messageData);
  });

  return Promise.all(tasks);
};

Python

def detect_text(bucket: str, filename: str) -> None:
    """
    Extract the text from an image uploaded to Cloud Storage.

    Extract the text from an image uploaded to Cloud Storage, then
    publish messages requesting subscribing services translate the text
    to each target language and save the result.

    Args:
        bucket: name of GCS bucket in which the file is stored.
        filename: name of the file to be read.

    Returns:
        None; the output is written to stdout and Cloud Logging.
    """
    print("Looking for text in image {}".format(filename))

    futures = []

    image = vision.Image(
        source=vision.ImageSource(gcs_image_uri=f"gs://{bucket}/{filename}")
    )
    text_detection_response = vision_client.text_detection(image=image)
    annotations = text_detection_response.text_annotations

    if len(annotations) > 0:
        text = annotations[0].description
    else:
        text = ""

    print(f"Extracted text {text} from image ({len(text)} chars).")

    detect_language_response = translate_client.detect_language(text)
    src_lang = detect_language_response["language"]
    print(f"Detected language {src_lang} for text {text}.")

    # Submit a message to the bus for each target language
    to_langs = os.environ["TO_LANG"].split(",")
    for target_lang in to_langs:
        topic_name = os.environ["TRANSLATE_TOPIC"]
        if src_lang == target_lang or src_lang == "und":
            topic_name = os.environ["RESULT_TOPIC"]
        message = {
            "text": text,
            "filename": filename,
            "lang": target_lang,
            "src_lang": src_lang,
        }
        message_data = json.dumps(message).encode("utf-8")
        topic_path = publisher.topic_path(project_id, topic_name)
        future = publisher.publish(topic_path, data=message_data)
        futures.append(future)
    for future in futures:
        future.result()

Go

package ocr

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"cloud.google.com/go/pubsub"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
	"golang.org/x/text/language"
)

// detectText detects the text in an image using the Google Vision API.
func detectText(ctx context.Context, bucketName, fileName string) error {
	log.Printf("Looking for text in image %v", fileName)
	maxResults := 1
	image := &visionpb.Image{
		Source: &visionpb.ImageSource{
			GcsImageUri: fmt.Sprintf("gs://%s/%s", bucketName, fileName),
		},
	}
	annotations, err := visionClient.DetectTexts(ctx, image, &visionpb.ImageContext{}, maxResults)
	if err != nil {
		return fmt.Errorf("DetectTexts: %w", err)
	}
	text := ""
	if len(annotations) > 0 {
		text = annotations[0].Description
	}
	if len(annotations) == 0 || len(text) == 0 {
		log.Printf("No text detected in image %q. Returning early.", fileName)
		return nil
	}
	log.Printf("Extracted text %q from image (%d chars).", text, len(text))

	detectResponse, err := translateClient.DetectLanguage(ctx, []string{text})
	if err != nil {
		return fmt.Errorf("DetectLanguage: %w", err)
	}
	if len(detectResponse) == 0 || len(detectResponse[0]) == 0 {
		return fmt.Errorf("DetectLanguage gave empty response")
	}
	srcLang := detectResponse[0][0].Language.String()
	log.Printf("Detected language %q for text %q.", srcLang, text)

	// Submit a message to the bus for each target language
	for _, targetLang := range toLang {
		topicName := translateTopic
		if srcLang == targetLang || srcLang == "und" { // detection returns "und" for undefined language
			topicName = resultTopic
		}
		targetTag, err := language.Parse(targetLang)
		if err != nil {
			return fmt.Errorf("language.Parse: %w", err)
		}
		srcTag, err := language.Parse(srcLang)
		if err != nil {
			return fmt.Errorf("language.Parse: %w", err)
		}
		message, err := json.Marshal(ocrMessage{
			Text:     text,
			FileName: fileName,
			Lang:     targetTag,
			SrcLang:  srcTag,
		})
		if err != nil {
			return fmt.Errorf("json.Marshal: %w", err)
		}
		topic := pubsubClient.Topic(topicName)
		ok, err := topic.Exists(ctx)
		if err != nil {
			return fmt.Errorf("Exists: %w", err)
		}
		if !ok {
			topic, err = pubsubClient.CreateTopic(ctx, topicName)
			if err != nil {
				return fmt.Errorf("CreateTopic: %w", err)
			}
		}
		msg := &pubsub.Message{
			Data: []byte(message),
		}
		if _, err = topic.Publish(ctx, msg).Get(ctx); err != nil {
			return fmt.Errorf("Get: %w", err)
		}
	}
	return nil
}

Java

private void detectText(String bucket, String filename) {
  logger.info("Looking for text in image " + filename);

  List<AnnotateImageRequest> visionRequests = new ArrayList<>();
  String gcsPath = String.format("gs://%s/%s", bucket, filename);

  ImageSource imgSource = ImageSource.newBuilder().setGcsImageUri(gcsPath).build();
  Image img = Image.newBuilder().setSource(imgSource).build();

  Feature textFeature = Feature.newBuilder().setType(Feature.Type.TEXT_DETECTION).build();
  AnnotateImageRequest visionRequest =
      AnnotateImageRequest.newBuilder().addFeatures(textFeature).setImage(img).build();
  visionRequests.add(visionRequest);

  // Detect text in an image using the Cloud Vision API
  AnnotateImageResponse visionResponse;
  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    visionResponse = client.batchAnnotateImages(visionRequests).getResponses(0);
    if (visionResponse == null || !visionResponse.hasFullTextAnnotation()) {
      logger.info(String.format("Image %s contains no text", filename));
      return;
    }

    if (visionResponse.hasError()) {
      // Log error
      logger.log(
          Level.SEVERE, "Error in vision API call: " + visionResponse.getError().getMessage());
      return;
    }
  } catch (IOException e) {
    // Log error (since IOException cannot be thrown by a Cloud Function)
    logger.log(Level.SEVERE, "Error detecting text: " + e.getMessage(), e);
    return;
  }

  String text = visionResponse.getFullTextAnnotation().getText();
  logger.info("Extracted text from image: " + text);

  // Detect language using the Cloud Translation API
  DetectLanguageRequest languageRequest =
      DetectLanguageRequest.newBuilder()
          .setParent(LOCATION_NAME)
          .setMimeType("text/plain")
          .setContent(text)
          .build();
  DetectLanguageResponse languageResponse;
  try (TranslationServiceClient client = TranslationServiceClient.create()) {
    languageResponse = client.detectLanguage(languageRequest);
  } catch (IOException e) {
    // Log error (since IOException cannot be thrown by a function)
    logger.log(Level.SEVERE, "Error detecting language: " + e.getMessage(), e);
    return;
  }

  if (languageResponse.getLanguagesCount() == 0) {
    logger.info("No languages were detected for text: " + text);
    return;
  }

  String languageCode = languageResponse.getLanguages(0).getLanguageCode();
  logger.info(String.format("Detected language %s for file %s", languageCode, filename));

  // Send a Pub/Sub translation request for every language we're going to translate to
  for (String targetLanguage : TO_LANGS) {
    logger.info("Sending translation request for language " + targetLanguage);
    OcrTranslateApiMessage message = new OcrTranslateApiMessage(text, filename, targetLanguage);
    ByteString byteStr = ByteString.copyFrom(message.toPubsubData());
    PubsubMessage pubsubApiMessage = PubsubMessage.newBuilder().setData(byteStr).build();
    try {
      publisher.publish(pubsubApiMessage).get();
    } catch (InterruptedException | ExecutionException e) {
      // Log error
      logger.log(Level.SEVERE, "Error publishing translation request: " + e.getMessage(), e);
      return;
    }
  }
}

翻譯文字

下列函式會翻譯擷取的文字，並將翻譯的文字排入存回 Cloud Storage 的佇列中：

Node.js

/**
 * This function is exported by index.js, and is executed when
 * a message is published to the Cloud Pub/Sub topic specified
 * by the TRANSLATE_TOPIC environment variable. The function
 * translates text using the Google Translate API.
 *
 * @param {object} event The Cloud Pub/Sub Message object.
 * @param {string} {messageObject}.data The "data" property of the Cloud Pub/Sub
 * Message. This property will be a base64-encoded string that you must decode.
 */
exports.translateText = async event => {
  const pubsubData = event.data;
  const jsonStr = Buffer.from(pubsubData, 'base64').toString();
  const {text, filename, lang} = JSON.parse(jsonStr);

  if (!text) {
    throw new Error(
      'Text not provided. Make sure you have a "text" property in your request'
    );
  }
  if (!filename) {
    throw new Error(
      'Filename not provided. Make sure you have a "filename" property in your request'
    );
  }
  if (!lang) {
    throw new Error(
      'Language not provided. Make sure you have a "lang" property in your request'
    );
  }

  console.log(`Translating text into ${lang}`);
  const [translation] = await translate.translate(text, lang);

  console.log('Translated text:', translation);

  const messageData = {
    text: translation,
    filename: filename,
    lang: lang,
  };

  await publishResult(process.env.RESULT_TOPIC, messageData);
  console.log(`Text translated to ${lang}`);
};

Python

def translate_text(event: dict, context: dict) -> None:
    """Cloud Function triggered by PubSub when a message is received from
    a subscription.

    Translates the text in the message from the specified source language
    to the requested target language, then sends a message requesting another
    service save the result.

    Args:
        event: dictionary containing the PubSub event.
        context: a dictionary containing metadata about the event.

    Returns:
        None; the output is written to stdout and Cloud Logging.
    """
    if event.get("data"):
        message_data = base64.b64decode(event["data"]).decode("utf-8")
        message = json.loads(message_data)
    else:
        raise ValueError("Data sector is missing in the Pub/Sub message.")

    text = validate_message(message, "text")
    filename = validate_message(message, "filename")
    target_lang = validate_message(message, "lang")
    src_lang = validate_message(message, "src_lang")

    print(f"Translating text into {target_lang}.")
    translated_text = translate_client.translate(
        text, target_language=target_lang, source_language=src_lang
    )
    topic_name = os.environ["RESULT_TOPIC"]
    message = {
        "text": translated_text["translatedText"],
        "filename": filename,
        "lang": target_lang,
    }
    encoded_message = json.dumps(message).encode("utf-8")
    topic_path = publisher.topic_path(project_id, topic_name)
    future = publisher.publish(topic_path, data=encoded_message)
    future.result()

Go

package ocr

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"cloud.google.com/go/pubsub"
	"cloud.google.com/go/translate"
)

// TranslateText is executed when a message is published to the Cloud Pub/Sub
// topic specified by the TRANSLATE_TOPIC environment variable, and translates
// the text using the Google Translate API.
func TranslateText(ctx context.Context, event PubSubMessage) error {
	if err := setup(ctx); err != nil {
		return fmt.Errorf("setup: %w", err)
	}
	if event.Data == nil {
		return fmt.Errorf("empty data")
	}
	var message ocrMessage
	if err := json.Unmarshal(event.Data, &message); err != nil {
		return fmt.Errorf("json.Unmarshal: %w", err)
	}

	log.Printf("Translating text into %s.", message.Lang.String())
	opts := translate.Options{
		Source: message.SrcLang,
	}
	translateResponse, err := translateClient.Translate(ctx, []string{message.Text}, message.Lang, &opts)
	if err != nil {
		return fmt.Errorf("Translate: %w", err)
	}
	if len(translateResponse) == 0 {
		return fmt.Errorf("Empty Translate response")
	}
	translatedText := translateResponse[0]

	messageData, err := json.Marshal(ocrMessage{
		Text:     translatedText.Text,
		FileName: message.FileName,
		Lang:     message.Lang,
		SrcLang:  message.SrcLang,
	})
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}

	topic := pubsubClient.Topic(resultTopic)
	ok, err := topic.Exists(ctx)
	if err != nil {
		return fmt.Errorf("Exists: %w", err)
	}
	if !ok {
		topic, err = pubsubClient.CreateTopic(ctx, resultTopic)
		if err != nil {
			return fmt.Errorf("CreateTopic: %w", err)
		}
	}
	msg := &pubsub.Message{
		Data: messageData,
	}
	if _, err = topic.Publish(ctx, msg).Get(ctx); err != nil {
		return fmt.Errorf("Get: %w", err)
	}
	log.Printf("Sent translation: %q", translatedText.Text)
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import com.google.cloud.pubsub.v1.Publisher;
import com.google.cloud.translate.v3.LocationName;
import com.google.cloud.translate.v3.TranslateTextRequest;
import com.google.cloud.translate.v3.TranslateTextResponse;
import com.google.cloud.translate.v3.TranslationServiceClient;
import com.google.protobuf.ByteString;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.PubsubMessage;
import functions.eventpojos.Message;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.ExecutionException;
import java.util.logging.Level;
import java.util.logging.Logger;

public class OcrTranslateText implements BackgroundFunction<Message> {
  private static final Logger logger = Logger.getLogger(OcrTranslateText.class.getName());

  // TODO<developer> set these environment variables
  private static final String PROJECT_ID = getenv("GCP_PROJECT");
  private static final String RESULTS_TOPIC_NAME = getenv("RESULT_TOPIC");
  private static final String LOCATION_NAME = LocationName.of(PROJECT_ID, "global").toString();

  private Publisher publisher;

  public OcrTranslateText() throws IOException {
    publisher = Publisher.newBuilder(
        ProjectTopicName.of(PROJECT_ID, RESULTS_TOPIC_NAME)).build();
  }

  @Override
  public void accept(Message pubSubMessage, Context context) {
    OcrTranslateApiMessage ocrMessage = OcrTranslateApiMessage.fromPubsubData(
        pubSubMessage.getData().getBytes(StandardCharsets.UTF_8));

    String targetLang = ocrMessage.getLang();
    logger.info("Translating text into " + targetLang);

    // Translate text to target language
    String text = ocrMessage.getText();
    TranslateTextRequest request =
        TranslateTextRequest.newBuilder()
            .setParent(LOCATION_NAME)
            .setMimeType("text/plain")
            .setTargetLanguageCode(targetLang)
            .addContents(text)
            .build();

    TranslateTextResponse response;
    try (TranslationServiceClient client = TranslationServiceClient.create()) {
      response = client.translateText(request);
    } catch (IOException e) {
      // Log error (since IOException cannot be thrown by a function)
      logger.log(Level.SEVERE, "Error translating text: " + e.getMessage(), e);
      return;
    }
    if (response.getTranslationsCount() == 0) {
      return;
    }

    String translatedText = response.getTranslations(0).getTranslatedText();
    logger.info("Translated text: " + translatedText);

    // Send translated text to (subsequent) Pub/Sub topic
    String filename = ocrMessage.getFilename();
    OcrTranslateApiMessage translateMessage = new OcrTranslateApiMessage(
        translatedText, filename, targetLang);
    try {
      ByteString byteStr = ByteString.copyFrom(translateMessage.toPubsubData());
      PubsubMessage pubsubApiMessage = PubsubMessage.newBuilder().setData(byteStr).build();

      publisher.publish(pubsubApiMessage).get();
      logger.info("Text translated to " + targetLang);
    } catch (InterruptedException | ExecutionException e) {
      // Log error (since these exception types cannot be thrown by a function)
      logger.log(Level.SEVERE, "Error publishing translation save request: " + e.getMessage(), e);
    }
  }

  // Avoid ungraceful deployment failures due to unset environment variables.
  // If you get this warning you should redeploy with the variable set.
  private static String getenv(String name) {
    String value = System.getenv(name);
    if (value == null) {
      logger.warning("Environment variable " + name + " was not set");
      value = "MISSING";
    }
    return value;
  }
}

儲存翻譯

最後，下列函式會接收翻譯的文字，並將文字存回 Cloud Storage：

Node.js

/**
 * This function is exported by index.js, and is executed when
 * a message is published to the Cloud Pub/Sub topic specified
 * by the RESULT_TOPIC environment variable. The function saves
 * the data packet to a file in GCS.
 *
 * @param {object} event The Cloud Pub/Sub Message object.
 * @param {string} {messageObject}.data The "data" property of the Cloud Pub/Sub
 * Message. This property will be a base64-encoded string that you must decode.
 */
exports.saveResult = async event => {
  const pubsubData = event.data;
  const jsonStr = Buffer.from(pubsubData, 'base64').toString();
  const {text, filename, lang} = JSON.parse(jsonStr);

  if (!text) {
    throw new Error(
      'Text not provided. Make sure you have a "text" property in your request'
    );
  }
  if (!filename) {
    throw new Error(
      'Filename not provided. Make sure you have a "filename" property in your request'
    );
  }
  if (!lang) {
    throw new Error(
      'Language not provided. Make sure you have a "lang" property in your request'
    );
  }

  console.log(`Received request to save file ${filename}`);

  const bucketName = process.env.RESULT_BUCKET;
  const newFilename = renameImageForSave(filename, lang);
  const file = storage.bucket(bucketName).file(newFilename);

  console.log(`Saving result to ${newFilename} in bucket ${bucketName}`);

  await file.save(text);
  console.log('File saved.');
};

Python

def save_result(event: dict, context: dict) -> None:
    """
    Cloud Function triggered by PubSub when a message is received from
    a subscription.

    Args:
        event: dictionary containing the PubSub event.
        context: a dictionary containing metadata about the event.

    Returns:
        None; the output is written to stdout and Cloud Logging.
    """
    if event.get("data"):
        message_data = base64.b64decode(event["data"]).decode("utf-8")
        message = json.loads(message_data)
    else:
        raise ValueError("Data sector is missing in the Pub/Sub message.")

    text = validate_message(message, "text")
    filename = validate_message(message, "filename")
    lang = validate_message(message, "lang")

    print(f"Received request to save file {filename}.")

    bucket_name = os.environ["RESULT_BUCKET"]
    result_filename = f"{filename}_{lang}.txt"
    bucket = storage_client.get_bucket(bucket_name)
    blob = bucket.blob(result_filename)

    print(f"Saving result to {result_filename} in bucket {bucket_name}.")

    blob.upload_from_string(text)

    print("File saved.")

Go

package ocr

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
)

// SaveResult is executed when a message is published to the Cloud Pub/Sub topic
// specified by the RESULT_TOPIC environment vairable, and saves the data packet
// to a file in GCS.
func SaveResult(ctx context.Context, event PubSubMessage) error {
	if err := setup(ctx); err != nil {
		return fmt.Errorf("ProcessImage: %w", err)
	}
	var message ocrMessage
	if event.Data == nil {
		return fmt.Errorf("Empty data")
	}
	if err := json.Unmarshal(event.Data, &message); err != nil {
		return fmt.Errorf("json.Unmarshal: %w", err)
	}
	log.Printf("Received request to save file %q.", message.FileName)

	resultFilename := fmt.Sprintf("%s_%s.txt", message.FileName, message.Lang)
	bucket := storageClient.Bucket(resultBucket)

	log.Printf("Saving result to %q in bucket %q.", resultFilename, resultBucket)

	w := bucket.Object(resultFilename).NewWriter(ctx)
	defer w.Close()
	fmt.Fprint(w, message.Text)

	log.Printf("File saved.")
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import functions.eventpojos.PubsubMessage;
import java.nio.charset.StandardCharsets;
import java.util.logging.Logger;

public class OcrSaveResult implements BackgroundFunction<PubsubMessage> {
  // TODO<developer> set this environment variable
  private static final String RESULT_BUCKET = System.getenv("RESULT_BUCKET");

  private static final Storage STORAGE = StorageOptions.getDefaultInstance().getService();
  private static final Logger logger = Logger.getLogger(OcrSaveResult.class.getName());

  @Override
  public void accept(PubsubMessage pubSubMessage, Context context) {
    OcrTranslateApiMessage ocrMessage = OcrTranslateApiMessage.fromPubsubData(
        pubSubMessage.getData().getBytes(StandardCharsets.UTF_8));

    logger.info("Received request to save file " +  ocrMessage.getFilename());

    String newFileName = String.format(
        "%s_to_%s.txt", ocrMessage.getFilename(), ocrMessage.getLang());

    // Save file to RESULT_BUCKET with name newFileNaem
    logger.info(String.format("Saving result to %s in bucket %s", newFileName, RESULT_BUCKET));
    BlobInfo blobInfo = BlobInfo.newBuilder(BlobId.of(RESULT_BUCKET, newFileName)).build();
    STORAGE.create(blobInfo, ocrMessage.getText().getBytes(StandardCharsets.UTF_8));
    logger.info("File saved");
  }
}

部署函式

1. 如要使用 Cloud Storage 觸發條件部署圖片處理函式，請在包含程式碼範例的目錄中執行下列指令 (如果是 Java，則是在 pom.xml 檔案中執行)：

   Node.js

   gcloud functions deploy ocr-extract \
   --runtime nodejs22 \
   --trigger-bucket YOUR_IMAGE_BUCKET_NAME \
   --entry-point processImage \
   --set-env-vars "^:^GCP_PROJECT=YOUR_GCP_PROJECT_ID:TRANSLATE_TOPIC=YOUR_TRANSLATE_TOPIC_NAME:RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME:TO_LANG=es,en,fr,ja"

   使用 --runtime 旗標指定 Node.js 支援版本的執行階段 ID，執行函式。

   Python

   gcloud functions deploy ocr-extract \
   --runtime python312 \
   --trigger-bucket YOUR_IMAGE_BUCKET_NAME \
   --entry-point process_image \
   --set-env-vars "^:^GCP_PROJECT=YOUR_GCP_PROJECT_ID:TRANSLATE_TOPIC=YOUR_TRANSLATE_TOPIC_NAME:RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME:TO_LANG=es,en,fr,ja"

   使用 --runtime 旗標指定 Python 支援版本的執行階段 ID，執行函式。

   注意： 如果使用 Python 3.7，可能需要在上述指令中排除一或多個預留的環境變數。

   Go

   gcloud functions deploy ocr-extract \
   --runtime go121 \
   --trigger-bucket YOUR_IMAGE_BUCKET_NAME \
   --entry-point ProcessImage \
   --set-env-vars "^:^GCP_PROJECT=YOUR_GCP_PROJECT_ID:TRANSLATE_TOPIC=YOUR_TRANSLATE_TOPIC_NAME:RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME:TO_LANG=es,en,fr,ja"

   使用 --runtime 旗標指定 Go 支援版本的執行階段 ID，執行函式。

   Java

   gcloud functions deploy ocr-extract \
   --entry-point functions.OcrProcessImage \
   --runtime java17 \
   --memory 512MB \
   --trigger-bucket YOUR_IMAGE_BUCKET_NAME \
   --set-env-vars "^:^GCP_PROJECT=YOUR_GCP_PROJECT_ID:TRANSLATE_TOPIC=YOUR_TRANSLATE_TOPIC_NAME:RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME:TO_LANG=es,en,fr,ja"

   使用 --runtime 旗標指定 Java 支援版本的執行階段 ID，執行函式。

   這個範例有多個函式，每個函式都有自己的子目錄，其中包含 pom.xml 檔案。部署這項函式時，請務必將 cd 納入至包含此檔案的適當子目錄。

   其中 YOUR_IMAGE_BUCKET_NAME 是您要上傳圖片的 Cloud Storage bucket 名稱。

2. 如要使用 Pub/Sub 觸發條件部署文字翻譯函式，請在包含程式碼範例的目錄中執行下列指令 (如果是 Java，則在 pom.xml 檔案中執行)：

   Node.js

   gcloud functions deploy ocr-translate \
   --runtime nodejs22 \
   --trigger-topic YOUR_TRANSLATE_TOPIC_NAME \
   --entry-point translateText \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME"

   使用 --runtime 旗標指定 Node.js 支援版本的執行階段 ID，執行函式。

   Python

   gcloud functions deploy ocr-translate \
   --runtime python312 \
   --trigger-topic YOUR_TRANSLATE_TOPIC_NAME \
   --entry-point translate_text \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME"

   使用 --runtime 旗標指定 Python 支援版本的執行階段 ID，執行函式。

   注意： 如果使用 Python 3.7，可能需要在上述指令中排除一或多個預留的環境變數。

   Go

   gcloud functions deploy ocr-translate \
   --runtime go121 \
   --trigger-topic YOUR_TRANSLATE_TOPIC_NAME \
   --entry-point TranslateText \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME"

   使用 --runtime 旗標指定 Go 支援版本的執行階段 ID，執行函式。

   Java

   gcloud functions deploy ocr-translate \
   --entry-point functions.OcrTranslateText \
   --runtime java17 \
   --memory 512MB \
   --trigger-topic YOUR_TRANSLATE_TOPIC_NAME \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_TOPIC=YOUR_RESULT_TOPIC_NAME"

   使用 --runtime 旗標指定 Java 支援版本的執行階段 ID，執行函式。

   這個範例有多個函式，每個函式都有自己的子目錄，其中包含 pom.xml 檔案。部署這項函式時，請務必將 cd 納入至包含此檔案的適當子目錄。

3. 如要使用 Cloud Pub/Sub 觸發條件部署函式，將結果儲存至 Cloud Storage，請在包含程式碼範例的目錄中執行下列指令 (如果是 Java，則是在 pom.xml 檔案中執行)：

   Node.js

   gcloud functions deploy ocr-save \
   --runtime nodejs22 \
   --trigger-topic YOUR_RESULT_TOPIC_NAME \
   --entry-point saveResult \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_BUCKET=YOUR_RESULT_BUCKET_NAME"

   使用 --runtime 旗標指定 Node.js 支援版本的執行階段 ID，執行函式。

   Python

   gcloud functions deploy ocr-save \
   --runtime python312 \
   --trigger-topic YOUR_RESULT_TOPIC_NAME \
   --entry-point save_result \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_BUCKET=YOUR_RESULT_BUCKET_NAME"

   使用 --runtime 旗標指定 Python 支援版本的執行階段 ID，執行函式。

   注意： 如果使用 Python 3.7，可能需要在上述指令中排除一或多個預留的環境變數。

   Go

   gcloud functions deploy ocr-save \
   --runtime go121 \
   --trigger-topic YOUR_RESULT_TOPIC_NAME \
   --entry-point SaveResult \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_BUCKET=YOUR_RESULT_BUCKET_NAME"

   使用 --runtime 旗標指定 Go 支援版本的執行階段 ID，執行函式。

   Java

   gcloud functions deploy ocr-save \
   --entry-point functions.OcrSaveResult \
   --runtime java17 \
   --memory 512MB \
   --trigger-topic YOUR_RESULT_TOPIC_NAME \
   --set-env-vars "GCP_PROJECT=YOUR_GCP_PROJECT_ID,RESULT_BUCKET=YOUR_RESULT_BUCKET_NAME"

   使用 --runtime 旗標指定 Java 支援版本的執行階段 ID，執行函式。

   這個範例有多個函式，每個函式都有自己的子目錄，其中包含 pom.xml 檔案。部署這項函式時，請務必將 cd 納入至包含此檔案的適當子目錄。

上傳圖片

1. 將圖片上傳至圖片 Cloud Storage bucket：

   gcloud storage cp PATH_TO_IMAGE gs://YOUR_IMAGE_BUCKET_NAME

   其中

   • PATH_TO_IMAGE 是本機系統中圖片檔 (內含文字) 的路徑。
   • YOUR_IMAGE_BUCKET_NAME 是您要上傳圖片的 bucket 名稱。

   您可以從範例專案下載其中一個圖片。

2. 觀察記錄以確定執行作業已完成：

   gcloud functions logs read --limit 100

3. 您可以在用於 YOUR_RESULT_BUCKET_NAME 的 Cloud Storage bucket 中查看儲存的翻譯內容。

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 帳戶收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。

刪除專案的方法如下：

注意：刪除專案會造成以下結果：

• 專案中的所有內容都會遭到刪除。如果使用現有專案來進行本文中的任務，刪除專案將一併移除當中已完成的其他任務'。
• 自訂專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案可避免超出專案配額限制。

1. 前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。

   前往「Manage resources」(管理資源)

2. 在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
3. 在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

刪除函式

刪除 Cloud Run functions 不會移除儲存在 Cloud Storage 中的任何資源。

如要刪除在本教學課程中建立的 Cloud Run functions，請執行下列指令：

gcloud functions delete ocr-extract
gcloud functions delete ocr-translate
gcloud functions delete ocr-save

您也可以從Google Cloud 控制台刪除 Cloud Run functions。