偵測圖片中的文字

如要偵測掃描文件中的文字，請試用 Document AI，進行光學字元辨識、結構化表單剖析和實體擷取。 您可以使用 Document AI Toolbox，將 Document AI 格式的輸出內容轉換為 Cloud Vision 格式。

在行動裝置應用程式中使用這個 API 嗎？請試用 Firebase 機器學習和 ML Kit，這兩項服務提供 Android 和 iOS 專用的 SDK，可使用 Cloud Vision 服務，以及裝置端 ML Vision API，並透過自訂 ML 模型進行裝置端推論。

光學字元辨識 (OCR)

Vision API 可偵測及擷取圖片中的文字。有兩項註解功能支援光學字元辨識 (OCR)：

• TEXT_DETECTION 會偵測並從任何圖片中擷取文字。舉例來說，相片可能含有路牌或交通號誌。JSON 包含整個擷取的字串、個別字詞，以及這些字詞的周框。

  

• DOCUMENT_TEXT_DETECTION 也會從圖片中擷取文字，但回覆內容經過最佳化，適用於密集文字和文件。JSON 包含網頁、區塊、段落、字詞和換行資訊。

  

  進一步瞭解如何DOCUMENT_TEXT_DETECTION從檔案 (PDF/TIFF) 擷取手寫內容和文字。

文字偵測要求

注意：Vision API 現已支援所有功能的離線非同步批次圖片註解。這項非同步要求最多支援 2000 個圖片檔案，並會傳回儲存在 Cloud Storage bucket 中的 JSON 回應檔案。如要進一步瞭解這項功能，請參閱離線批次圖片加註。

設定 Google Cloud 專案和驗證

如果您尚未建立 Google Cloud 專案，請立即建立。展開這個部分即可查看操作說明。

1. 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 (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

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Vision API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

4. Install the Google Cloud CLI.

5. 設定 gcloud CLI 以使用您的聯合身分。

   詳情請參閱「 使用聯合身分登入 gcloud CLI」。

6. 如要初始化 gcloud CLI，請執行下列指令：

   gcloud init

   偵測本機圖片中的文字

   您可以使用 Vision API 對本機圖片檔執行特徵偵測。

   如果是 REST 要求，請在要求主體中，以 base64 編碼字串的形式傳送圖片檔案內容。

   如果是 gcloud 和用戶端程式庫要求，請在要求中指定本機圖片的路徑。

   gcloud

   如要執行文字偵測，請使用 gcloud ml vision detect-text 指令，如下列範例所示：

   gcloud ml vision detect-text ./path/to/local/file.jpg
   

   REST

   使用任何要求資料之前，請先替換以下項目：

   • BASE64_ENCODED_IMAGE：二進位圖片資料的 Base64 表示法 (ASCII 字串)。這個字串應類似下列字串：
     • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
     如要瞭解詳情，請參閱 base64 編碼主題。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

   HTTP 方法和網址：

   POST https://vision.googleapis.com/v1/images:annotate

   JSON 要求主體：

   {
     "requests": [
       {
         "image": {
           "content": "BASE64_ENCODED_IMAGE"
         },
         "features": [
           {
             "type": "TEXT_DETECTION"
           }
         ]
       }
     ]
   }
   

   如要傳送要求，請選擇以下其中一個選項：

   curl

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "x-goog-user-project: PROJECT_ID" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://vision.googleapis.com/v1/images:annotate"

   PowerShell

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

   如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼與 JSON 格式的回應。

   TEXT_DETECTION 回應會包含偵測到的詞組、其周框，以及個別字詞和周框。

   Note: Zero coordinate values omitted. When the API detects a coordinate ("x" or "y") value of 0, that coordinate is omitted in the JSON response. Thus, a response with a bounding poly around the entire image would be
   [{},{"x": 100},{"x": 100,"y": 100},{"y": 100}] for an image that is 100 pixels by 100 pixels. For more information, see the API Reference documentation.

   回應

   {
     "responses": [
       {
         "textAnnotations": [
           {
             "locale": "en",
             "description": "WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE\n",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 341,
                   "y": 828
                 },
                 {
                   "x": 2249,
                   "y": 828
                 },
                 {
                   "x": 2249,
                   "y": 1993
                 },
                 {
                   "x": 341,
                   "y": 1993
                 }
               ]
             }
           },
           {
             "description": "WAITING?",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 352,
                   "y": 828
                 },
                 {
                   "x": 2248,
                   "y": 911
                 },
                 {
                   "x": 2238,
                   "y": 1148
                 },
                 {
                   "x": 342,
                   "y": 1065
                 }
               ]
             }
           },
           {
             "description": "PLEASE",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1210,
                   "y": 1233
                 },
                 {
                   "x": 1907,
                   "y": 1263
                 },
                 {
                   "x": 1902,
                   "y": 1383
                 },
                 {
                   "x": 1205,
                   "y": 1353
                 }
               ]
             }
           },
           {
             "description": "TURN",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1210,
                   "y": 1418
                 },
                 {
                   "x": 1730,
                   "y": 1441
                 },
                 {
                   "x": 1724,
                   "y": 1564
                 },
                 {
                   "x": 1205,
                   "y": 1541
                 }
               ]
             }
           },
           {
             "description": "OFF",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1792,
                   "y": 1443
                 },
                 {
                   "x": 2128,
                   "y": 1458
                 },
                 {
                   "x": 2122,
                   "y": 1581
                 },
                 {
                   "x": 1787,
                   "y": 1566
                 }
               ]
             }
           },
           {
             "description": "YOUR",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1219,
                   "y": 1603
                 },
                 {
                   "x": 1746,
                   "y": 1629
                 },
                 {
                   "x": 1740,
                   "y": 1759
                 },
                 {
                   "x": 1213,
                   "y": 1733
                 }
               ]
             }
           },
           {
             "description": "ENGINE",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1222,
                   "y": 1771
                 },
                 {
                   "x": 1944,
                   "y": 1834
                 },
                 {
                   "x": 1930,
                   "y": 1992
                 },
                 {
                   "x": 1208,
                   "y": 1928
                 }
               ]
             }
           }
         ],
         "fullTextAnnotation": {
           "pages": [
                     ...
                     ]
                   },
                   "paragraphs": [
                         ...
                         ]
                       },
                       "words": [
                           ...
                           },
                           "symbols": [
                           ...
                         }
                       ]
                     }
                   ],
                   "blockType": "TEXT"
                 },
                 ...
               ]
             }
           ],
           "text": "WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE\n"
         }
       }
     ]
   }
   

   Go

   在試用這個範例之前，請先按照Go「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Go API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   
   // detectText gets text from the Vision API for an image at the given file path.
   func detectText(w io.Writer, file string) error {
   	ctx := context.Background()
   
   	client, err := vision.NewImageAnnotatorClient(ctx)
   	if err != nil {
   		return err
   	}
   
   	f, err := os.Open(file)
   	if err != nil {
   		return err
   	}
   	defer f.Close()
   
   	image, err := vision.NewImageFromReader(f)
   	if err != nil {
   		return err
   	}
   	annotations, err := client.DetectTexts(ctx, image, nil, 10)
   	if err != nil {
   		return err
   	}
   
   	if len(annotations) == 0 {
   		fmt.Fprintln(w, "No text found.")
   	} else {
   		fmt.Fprintln(w, "Text:")
   		for _, annotation := range annotations {
   			fmt.Fprintf(w, "%q\n", annotation.Description)
   		}
   	}
   
   	return nil
   }
   

   Java

   在試用這個範例之前，請先按照使用用戶端程式庫的 Vision API 快速入門導覽課程中的 Java 設定操作說明進行操作。詳情請參閱 Vision API Java 參考說明文件。

   注意：Java Spring Framework 使用者可以透過 Spring Cloud Google Cloud 自動設定驗證設定和用戶端物件，以使用 Vision API。

   
   import com.google.cloud.vision.v1.AnnotateImageRequest;
   import com.google.cloud.vision.v1.AnnotateImageResponse;
   import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
   import com.google.cloud.vision.v1.EntityAnnotation;
   import com.google.cloud.vision.v1.Feature;
   import com.google.cloud.vision.v1.Image;
   import com.google.cloud.vision.v1.ImageAnnotatorClient;
   import com.google.protobuf.ByteString;
   import java.io.FileInputStream;
   import java.io.IOException;
   import java.util.ArrayList;
   import java.util.List;
   
   public class DetectText {
     public static void detectText() throws IOException {
       // TODO(developer): Replace these variables before running the sample.
       String filePath = "path/to/your/image/file.jpg";
       detectText(filePath);
     }
   
     // Detects text in the specified image.
     public static void detectText(String filePath) throws IOException {
       List<AnnotateImageRequest> requests = new ArrayList<>();
   
       ByteString imgBytes = ByteString.readFrom(new FileInputStream(filePath));
   
       Image img = Image.newBuilder().setContent(imgBytes).build();
       Feature feat = Feature.newBuilder().setType(Feature.Type.TEXT_DETECTION).build();
       AnnotateImageRequest request =
           AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
       requests.add(request);
   
       // Initialize client that will be used to send requests. This client only needs to be created
       // once, and can be reused for multiple requests. After completing all of your requests, call
       // the "close" method on the client to safely clean up any remaining background resources.
       try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
         BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
         List<AnnotateImageResponse> responses = response.getResponsesList();
   
         for (AnnotateImageResponse res : responses) {
           if (res.hasError()) {
             System.out.format("Error: %s%n", res.getError().getMessage());
             return;
           }
   
           // For full list of available annotations, see http://g.co/cloud/vision/docs
           for (EntityAnnotation annotation : res.getTextAnnotationsList()) {
             System.out.format("Text: %s%n", annotation.getDescription());
             System.out.format("Position : %s%n", annotation.getBoundingPoly());
           }
         }
       }
     }
   }

   Node.js

   在試用這個範例之前，請先按照Node.js「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Node.js API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   const vision = require('@google-cloud/vision');
   
   // Creates a client
   const client = new vision.ImageAnnotatorClient();
   
   /**
    * TODO(developer): Uncomment the following line before running the sample.
    */
   // const fileName = 'Local image file, e.g. /path/to/image.png';
   
   // Performs text detection on the local file
   const [result] = await client.textDetection(fileName);
   const detections = result.textAnnotations;
   console.log('Text:');
   detections.forEach(text => console.log(text));

   Python

   在試用這個範例之前，請先按照Python「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Python API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   def detect_text(path):
       """Detects text in the file."""
       from google.cloud import vision
   
       client = vision.ImageAnnotatorClient()
   
       with open(path, "rb") as image_file:
           content = image_file.read()
   
       image = vision.Image(content=content)
   
       response = client.text_detection(image=image)
       texts = response.text_annotations
       print("Texts:")
   
       for text in texts:
           print(f'\n"{text.description}"')
   
           vertices = [
               f"({vertex.x},{vertex.y})" for vertex in text.bounding_poly.vertices
           ]
   
           print("bounds: {}".format(",".join(vertices)))
   
       if response.error.message:
           raise Exception(
               "{}\nFor more info on error messages, check: "
               "https://cloud.google.com/apis/design/errors".format(response.error.message)
           )
   
   

   其他語言

   C#： 請按照用戶端程式庫頁面上的C# 設定說明操作， 然後前往 .NET 適用的 Vision 參考說明文件。

   PHP： 請按照用戶端程式庫頁面上的 PHP 設定說明操作， 然後前往 PHP 適用的 Vision 參考文件。

   Ruby： 請按照用戶端程式庫頁面的 Ruby 設定說明操作， 然後前往 Ruby 適用的 Vision 參考說明文件。

   偵測遠端圖片中的文字

   您可以透過 Vision API，對位於 Cloud Storage 或網路上的遠端圖片檔案執行特徵偵測。如要傳送遠端檔案要求，請在要求內文中指定檔案的網頁網址或 Cloud Storage URI。

   注意：從 HTTP/HTTPS 網址擷取圖片時，Google 無法保證要求會完成。如果指定主機拒絕要求 (例如因要求節流或DoS防範)，或 Google 為防範濫用行為而節流對網站的要求，您的要求可能會失敗。最佳做法是不要在正式版應用程式中，使用外部託管圖片。

   gcloud

   如要執行文字偵測，請使用 gcloud ml vision detect-text 指令，如下列範例所示：

   gcloud ml vision detect-text gs://cloud-samples-data/vision/ocr/sign.jpg
   

   REST

   使用任何要求資料之前，請先替換以下項目：

   • CLOUD_STORAGE_IMAGE_URI：Cloud Storage 值區中有效圖片檔案的路徑。您必須至少擁有檔案的讀取權限。 範例：
     • gs://cloud-samples-data/vision/ocr/sign.jpg

   • PROJECT_ID：您的 Google Cloud 專案 ID。

   HTTP 方法和網址：

   POST https://vision.googleapis.com/v1/images:annotate

   JSON 要求主體：

   {
     "requests": [
       {
         "image": {
           "source": {
             "imageUri": "CLOUD_STORAGE_IMAGE_URI"
           }
          },
          "features": [
            {
              "type": "TEXT_DETECTION"
            }
          ]
       }
     ]
   }
   

   如要傳送要求，請選擇以下其中一個選項：

   curl

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "x-goog-user-project: PROJECT_ID" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://vision.googleapis.com/v1/images:annotate"

   PowerShell

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

   如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼與 JSON 格式的回應。

   TEXT_DETECTION 回應會包含偵測到的詞組、其周框，以及個別字詞和周框。

   Note: Zero coordinate values omitted. When the API detects a coordinate ("x" or "y") value of 0, that coordinate is omitted in the JSON response. Thus, a response with a bounding poly around the entire image would be
   [{},{"x": 100},{"x": 100,"y": 100},{"y": 100}] for an image that is 100 pixels by 100 pixels. For more information, see the API Reference documentation.

   回應

   {
     "responses": [
       {
         "textAnnotations": [
           {
             "locale": "en",
             "description": "WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE\n",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 341,
                   "y": 828
                 },
                 {
                   "x": 2249,
                   "y": 828
                 },
                 {
                   "x": 2249,
                   "y": 1993
                 },
                 {
                   "x": 341,
                   "y": 1993
                 }
               ]
             }
           },
           {
             "description": "WAITING?",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 352,
                   "y": 828
                 },
                 {
                   "x": 2248,
                   "y": 911
                 },
                 {
                   "x": 2238,
                   "y": 1148
                 },
                 {
                   "x": 342,
                   "y": 1065
                 }
               ]
             }
           },
           {
             "description": "PLEASE",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1210,
                   "y": 1233
                 },
                 {
                   "x": 1907,
                   "y": 1263
                 },
                 {
                   "x": 1902,
                   "y": 1383
                 },
                 {
                   "x": 1205,
                   "y": 1353
                 }
               ]
             }
           },
           {
             "description": "TURN",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1210,
                   "y": 1418
                 },
                 {
                   "x": 1730,
                   "y": 1441
                 },
                 {
                   "x": 1724,
                   "y": 1564
                 },
                 {
                   "x": 1205,
                   "y": 1541
                 }
               ]
             }
           },
           {
             "description": "OFF",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1792,
                   "y": 1443
                 },
                 {
                   "x": 2128,
                   "y": 1458
                 },
                 {
                   "x": 2122,
                   "y": 1581
                 },
                 {
                   "x": 1787,
                   "y": 1566
                 }
               ]
             }
           },
           {
             "description": "YOUR",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1219,
                   "y": 1603
                 },
                 {
                   "x": 1746,
                   "y": 1629
                 },
                 {
                   "x": 1740,
                   "y": 1759
                 },
                 {
                   "x": 1213,
                   "y": 1733
                 }
               ]
             }
           },
           {
             "description": "ENGINE",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1222,
                   "y": 1771
                 },
                 {
                   "x": 1944,
                   "y": 1834
                 },
                 {
                   "x": 1930,
                   "y": 1992
                 },
                 {
                   "x": 1208,
                   "y": 1928
                 }
               ]
             }
           }
         ],
         "fullTextAnnotation": {
           "pages": [
                     ...
                     ]
                   },
                   "paragraphs": [
                         ...
                         ]
                       },
                       "words": [
                           ...
                           },
                           "symbols": [
                           ...
                         }
                       ]
                     }
                   ],
                   "blockType": "TEXT"
                 },
                 ...
               ]
             }
           ],
           "text": "WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE\n"
         }
       }
     ]
   }
   

   Go

   在試用這個範例之前，請先按照Go「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Go API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   
   // detectText gets text from the Vision API for an image at the given file path.
   func detectTextURI(w io.Writer, file string) error {
   	ctx := context.Background()
   
   	client, err := vision.NewImageAnnotatorClient(ctx)
   	if err != nil {
   		return err
   	}
   
   	image := vision.NewImageFromURI(file)
   	annotations, err := client.DetectTexts(ctx, image, nil, 10)
   	if err != nil {
   		return err
   	}
   
   	if len(annotations) == 0 {
   		fmt.Fprintln(w, "No text found.")
   	} else {
   		fmt.Fprintln(w, "Text:")
   		for _, annotation := range annotations {
   			fmt.Fprintf(w, "%q\n", annotation.Description)
   		}
   	}
   
   	return nil
   }
   

   Java

   在試用這個範例之前，請先按照使用用戶端程式庫的 Vision API 快速入門導覽課程中的 Java 設定操作說明進行操作。詳情請參閱 Vision API Java 參考說明文件。

   注意：Java Spring Framework 使用者可以透過 Spring Cloud Google Cloud 自動設定驗證設定和用戶端物件，以使用 Vision API。

   
   import com.google.cloud.vision.v1.AnnotateImageRequest;
   import com.google.cloud.vision.v1.AnnotateImageResponse;
   import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
   import com.google.cloud.vision.v1.EntityAnnotation;
   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 java.io.IOException;
   import java.util.ArrayList;
   import java.util.List;
   
   public class DetectTextGcs {
   
     public static void detectTextGcs() throws IOException {
       // TODO(developer): Replace these variables before running the sample.
       String filePath = "gs://your-gcs-bucket/path/to/image/file.jpg";
       detectTextGcs(filePath);
     }
   
     // Detects text in the specified remote image on Google Cloud Storage.
     public static void detectTextGcs(String gcsPath) throws IOException {
       List<AnnotateImageRequest> requests = new ArrayList<>();
   
       ImageSource imgSource = ImageSource.newBuilder().setGcsImageUri(gcsPath).build();
       Image img = Image.newBuilder().setSource(imgSource).build();
       Feature feat = Feature.newBuilder().setType(Feature.Type.TEXT_DETECTION).build();
       AnnotateImageRequest request =
           AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
       requests.add(request);
   
       // Initialize client that will be used to send requests. This client only needs to be created
       // once, and can be reused for multiple requests. After completing all of your requests, call
       // the "close" method on the client to safely clean up any remaining background resources.
       try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
         BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
         List<AnnotateImageResponse> responses = response.getResponsesList();
   
         for (AnnotateImageResponse res : responses) {
           if (res.hasError()) {
             System.out.format("Error: %s%n", res.getError().getMessage());
             return;
           }
   
           // For full list of available annotations, see http://g.co/cloud/vision/docs
           for (EntityAnnotation annotation : res.getTextAnnotationsList()) {
             System.out.format("Text: %s%n", annotation.getDescription());
             System.out.format("Position : %s%n", annotation.getBoundingPoly());
           }
         }
       }
     }
   }

   Node.js

   在試用這個範例之前，請先按照Node.js「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Node.js API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   // Imports the Google Cloud client libraries
   const vision = require('@google-cloud/vision');
   
   // Creates a client
   const client = new vision.ImageAnnotatorClient();
   
   /**
    * TODO(developer): Uncomment the following lines before running the sample.
    */
   // const bucketName = 'Bucket where the file resides, e.g. my-bucket';
   // const fileName = 'Path to file within bucket, e.g. path/to/image.png';
   
   // Performs text detection on the gcs file
   const [result] = await client.textDetection(`gs://${bucketName}/${fileName}`);
   const detections = result.textAnnotations;
   console.log('Text:');
   detections.forEach(text => console.log(text));

   Python

   在試用這個範例之前，請先按照Python「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Python API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   def detect_text_uri(uri):
       """Detects text in the file located in Google Cloud Storage or on the Web."""
       from google.cloud import vision
   
       client = vision.ImageAnnotatorClient()
       image = vision.Image()
       image.source.image_uri = uri
   
       response = client.text_detection(image=image)
       texts = response.text_annotations
       print("Texts:")
   
       for text in texts:
           print(f'\n"{text.description}"')
   
           vertices = [
               f"({vertex.x},{vertex.y})" for vertex in text.bounding_poly.vertices
           ]
   
           print("bounds: {}".format(",".join(vertices)))
   
       if response.error.message:
           raise Exception(
               "{}\nFor more info on error messages, check: "
               "https://cloud.google.com/apis/design/errors".format(response.error.message)
           )
   
   

   其他語言

   C#： 請按照用戶端程式庫頁面上的C# 設定說明操作， 然後前往 .NET 適用的 Vision 參考說明文件。

   PHP： 請按照用戶端程式庫頁面上的 PHP 設定說明操作， 然後前往 PHP 適用的 Vision 參考文件。

   Ruby： 請按照用戶端程式庫頁面的 Ruby 設定說明操作， 然後前往 Ruby 適用的 Vision 參考說明文件。

   指定語言 (選用)

   這兩種 OCR 要求的其中一項支援一或多個 languageHints，可指定圖片中任何文字的語言。不過，空值通常會產生最佳結果，因為省略值可啟用自動語言偵測功能。如果語言使用拉丁字母，則不需要設定 languageHints。在少數情況下，如果知道圖片中文字的語言，設定提示有助於獲得更準確的結果 (但如果提示錯誤，可能會造成重大阻礙)。如果指定的一或多種語言不是支援的語言，文字偵測就會傳回錯誤。

   如要提供語言提示，請修改要求主體 (request.json 檔案)，在 imageContext.languageHints 欄位中提供其中一種支援語言的字串，如下列範例所示：

   {
     "requests": [
       {
         "image": {
           "source": {
             "imageUri": "IMAGE_URL"
           }
         },
         "features": [
           {
             "type": "DOCUMENT_TEXT_DETECTION"
           }
         ],
         "imageContext": {
           "languageHints": ["en-t-i0-handwrit"]
         }
       }
     ]
   }

   語言提示的運作方式為何？

   languageHint 格式遵循 BCP47 語言代碼格式設定規範。BCP47 指定的格式如下：

   language ["-" script] ["-" region] *("-" variant) *("-" extension) ["-" privateuse]。

   舉例來說，語言提示「en-t-i0-handwrit」指定了英文 (en)、轉換擴充功能單例項 (t)、輸入法引擎轉換擴充功能代碼 (i0)，以及手寫轉換代碼 (handwrit)。這段代碼表示語言為「從手寫轉換的英文」。您不需要指定指令碼代碼，因為「en」語言會隱含 Latn。

   多區域支援

   這項功能目前僅適用於 OCR 功能 (類型 TEXT_DETECTION 或 DOCUMENT_TEXT_DETECTION)。

   您現在可以指定洲際資料儲存空間和 OCR 處理作業。目前支援的地區如下：

   • us：僅限美國
   • eu：歐盟

   位置

   您可以控管專案資源的儲存和處理位置。具體來說，您可以設定 Cloud Vision，只在歐盟境內儲存及處理資料。

   根據預設，Cloud Vision 會在「全球」位置儲存及處理資源，也就是說，Cloud Vision 無法保證資源會保留在特定位置或區域。如果選擇「歐盟」，Google 只會在歐盟儲存及處理資料。您和使用者可以從任何位置存取資料。

   使用 API 設定位置資訊

   Vision API 支援全球 API 端點 (vision.googleapis.com)，以及兩個以區域為準的端點：歐盟端點 (eu-vision.googleapis.com) 和美國端點 (us-vision.googleapis.com)。請使用這些端點進行特定區域的處理作業。舉例來說，如要只在歐盟儲存及處理資料，請在 REST API 呼叫中使用 URI eu-vision.googleapis.com，取代 vision.googleapis.com：

   • https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:annotate
   • https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:asyncBatchAnnotate
   • https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:annotate
   • https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:asyncBatchAnnotate

   如要只在美國儲存及處理資料，請使用上述方法搭配美國端點 (us-vision.googleapis.com)。

   使用用戶端程式庫設定位置

   Vision API 用戶端程式庫預設會存取全域 API 端點 (vision.googleapis.com)。如要只在歐盟境內儲存及處理資料，您必須明確設定端點 (eu-vision.googleapis.com)。下列程式碼範例說明如何設定這項設定。

   REST

   使用任何要求資料之前，請先替換以下項目：

   • REGION_ID：有效的區域位置 ID 之一：
     • us：僅限美國
     • eu：歐盟
   • CLOUD_STORAGE_IMAGE_URI：Cloud Storage 值區中有效圖片檔案的路徑。您必須至少擁有檔案的讀取權限。 範例：
     • gs://cloud-samples-data/vision/ocr/sign.jpg

   • PROJECT_ID：您的 Google Cloud 專案 ID。

   HTTP 方法和網址：

   POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/images:annotate

   JSON 要求主體：

   {
     "requests": [
       {
         "image": {
           "source": {
             "imageUri": "CLOUD_STORAGE_IMAGE_URI"
           }
          },
          "features": [
            {
              "type": "TEXT_DETECTION"
            }
          ]
       }
     ]
   }
   

   如要傳送要求，請選擇以下其中一個選項：

   curl

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "x-goog-user-project: PROJECT_ID" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/images:annotate"

   PowerShell

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/images:annotate" | Select-Object -Expand Content

   如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼與 JSON 格式的回應。

   TEXT_DETECTION 回應會包含偵測到的詞組、其周框，以及個別字詞和周框。

   Note: Zero coordinate values omitted. When the API detects a coordinate ("x" or "y") value of 0, that coordinate is omitted in the JSON response. Thus, a response with a bounding poly around the entire image would be
   [{},{"x": 100},{"x": 100,"y": 100},{"y": 100}] for an image that is 100 pixels by 100 pixels. For more information, see the API Reference documentation.

   回應

   {
     "responses": [
       {
         "textAnnotations": [
           {
             "locale": "en",
             "description": "WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE\n",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 341,
                   "y": 828
                 },
                 {
                   "x": 2249,
                   "y": 828
                 },
                 {
                   "x": 2249,
                   "y": 1993
                 },
                 {
                   "x": 341,
                   "y": 1993
                 }
               ]
             }
           },
           {
             "description": "WAITING?",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 352,
                   "y": 828
                 },
                 {
                   "x": 2248,
                   "y": 911
                 },
                 {
                   "x": 2238,
                   "y": 1148
                 },
                 {
                   "x": 342,
                   "y": 1065
                 }
               ]
             }
           },
           {
             "description": "PLEASE",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1210,
                   "y": 1233
                 },
                 {
                   "x": 1907,
                   "y": 1263
                 },
                 {
                   "x": 1902,
                   "y": 1383
                 },
                 {
                   "x": 1205,
                   "y": 1353
                 }
               ]
             }
           },
           {
             "description": "TURN",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1210,
                   "y": 1418
                 },
                 {
                   "x": 1730,
                   "y": 1441
                 },
                 {
                   "x": 1724,
                   "y": 1564
                 },
                 {
                   "x": 1205,
                   "y": 1541
                 }
               ]
             }
           },
           {
             "description": "OFF",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1792,
                   "y": 1443
                 },
                 {
                   "x": 2128,
                   "y": 1458
                 },
                 {
                   "x": 2122,
                   "y": 1581
                 },
                 {
                   "x": 1787,
                   "y": 1566
                 }
               ]
             }
           },
           {
             "description": "YOUR",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1219,
                   "y": 1603
                 },
                 {
                   "x": 1746,
                   "y": 1629
                 },
                 {
                   "x": 1740,
                   "y": 1759
                 },
                 {
                   "x": 1213,
                   "y": 1733
                 }
               ]
             }
           },
           {
             "description": "ENGINE",
             "boundingPoly": {
               "vertices": [
                 {
                   "x": 1222,
                   "y": 1771
                 },
                 {
                   "x": 1944,
                   "y": 1834
                 },
                 {
                   "x": 1930,
                   "y": 1992
                 },
                 {
                   "x": 1208,
                   "y": 1928
                 }
               ]
             }
           }
         ],
         "fullTextAnnotation": {
           "pages": [
                     ...
                     ]
                   },
                   "paragraphs": [
                         ...
                         ]
                       },
                       "words": [
                           ...
                           },
                           "symbols": [
                           ...
                         }
                       ]
                     }
                   ],
                   "blockType": "TEXT"
                 },
                 ...
               ]
             }
           ],
           "text": "WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE\n"
         }
       }
     ]
   }
   

   Go

   在試用這個範例之前，請先按照Go「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Go API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   import (
   	"context"
   	"fmt"
   
   	vision "cloud.google.com/go/vision/apiv1"
   	"google.golang.org/api/option"
   )
   
   // setEndpoint changes your endpoint.
   func setEndpoint(endpoint string) error {
   	// endpoint := "eu-vision.googleapis.com:443"
   
   	ctx := context.Background()
   	client, err := vision.NewImageAnnotatorClient(ctx, option.WithEndpoint(endpoint))
   	if err != nil {
   		return fmt.Errorf("NewImageAnnotatorClient: %w", err)
   	}
   	defer client.Close()
   
   	return nil
   }
   

   Java

   在試用這個範例之前，請先按照使用用戶端程式庫的 Vision API 快速入門導覽課程中的 Java 設定操作說明進行操作。詳情請參閱 Vision API Java 參考說明文件。

   注意：Java Spring Framework 使用者可以透過 Spring Cloud Google Cloud 自動設定驗證設定和用戶端物件，以使用 Vision API。

   ImageAnnotatorSettings settings =
       ImageAnnotatorSettings.newBuilder().setEndpoint("eu-vision.googleapis.com:443").build();
   
   // Initialize client that will be used to send requests. This client only needs to be created
   // once, and can be reused for multiple requests. After completing all of your requests, call
   // the "close" method on the client to safely clean up any remaining background resources.
   ImageAnnotatorClient client = ImageAnnotatorClient.create(settings);

   Node.js

   在試用這個範例之前，請先按照Node.js「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Node.js API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   // Imports the Google Cloud client library
   const vision = require('@google-cloud/vision');
   
   async function setEndpoint() {
     // Specifies the location of the api endpoint
     const clientOptions = {apiEndpoint: 'eu-vision.googleapis.com'};
   
     // Creates a client
     const client = new vision.ImageAnnotatorClient(clientOptions);
   
     // Performs text detection on the image file
     const [result] = await client.textDetection('./resources/wakeupcat.jpg');
     const labels = result.textAnnotations;
     console.log('Text:');
     labels.forEach(label => console.log(label.description));
   }
   setEndpoint();

   Python

   在試用這個範例之前，請先按照Python「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Python API 參考說明文件。

   如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

   from google.cloud import vision
   
   client_options = {"api_endpoint": "eu-vision.googleapis.com"}
   
   client = vision.ImageAnnotatorClient(client_options=client_options)

   試試看

   請試試下方的文字偵測和文件文字偵測。您可以點選「執行」，使用已指定的圖片 (gs://cloud-samples-data/vision/ocr/sign.jpg)，也可以指定自己的圖片。

   如要試用文件文字偵測功能，請將 type 的值更新為 DOCUMENT_TEXT_DETECTION。

   

   要求主體：

   {
     "requests": [
       {
         "features": [
           {
             "type": "TEXT_DETECTION"
           }
         ],
         "image": {
           "source": {
             "imageUri": "gs://cloud-samples-data/vision/ocr/sign.jpg"
           }
         }
       }
     ]
   }