זיהוי טקסט בקבצים (PDF/TIFF)

‫Vision API יכול לזהות ולתמלל טקסט מקובצי PDF ו-TIFF ששמורים ב-Cloud Storage.

כדי לזהות טקסט במסמכי PDF ו-TIFF, צריך לשלוח בקשה באמצעות הפונקציה files:asyncBatchAnnotate. הפונקציה הזו מבצעת בקשה אופליין (אסינכרונית) ומספקת את הסטטוס שלה באמצעות משאבי operations.

הפלט מבקשת PDF/TIFF נכתב לקובץ JSON שנוצר בקטגוריה של Cloud Storage שצוינה.

מגבלות

‫Vision API מקבל קובצי PDF או TIFF של עד 2,000 דפים. קבצים גדולים יותר יחזירו שגיאה.

אימות

אין תמיכה במפתחות API לבקשות files:asyncBatchAnnotate. הוראות לאימות באמצעות חשבון שירות מופיעות במאמר שימוש בחשבון שירות.

לחשבון שמשמש לאימות צריכה להיות גישה לקטגוריה של Cloud Storage שציינתם לפלט (roles/editor או roles/storage.objectCreator ומעלה).

אפשר להשתמש במפתח API כדי לשלוח שאילתה לגבי סטטוס הפעולה. הוראות מפורטות זמינות במאמר שימוש במפתח API.

בקשות לזיהוי טקסט במסמך

כרגע, זיהוי מסמכי PDF/TIFF זמין רק לקבצים שמאוחסנים בקטגוריות של Cloud Storage. קובצי JSON של תגובות נשמרים באופן דומה בקטגוריה של Cloud Storage.

דף PDF של מפקד האוכלוסין בארה"ב משנת 2010
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf, מקור: United States Census Bureau.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫CLOUD_STORAGE_BUCKET: קטגוריה או ספרייה ב-Cloud Storage לשמירת קובצי הפלט, בפורמט הבא:
    • gs://bucket/directory/
    למשתמש ששולח את הבקשה צריכה להיות הרשאת כתיבה לקטגוריה.
  • ‫CLOUD_STORAGE_FILE_URI: הנתיב לקובץ תקין (PDF/TIFF) בקטגוריה של Cloud Storage. צריכות להיות לכם לפחות הרשאות קריאה לקובץ. דוגמה: 
    • gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
  • FEATURE_TYPE: סוג תכונה תקין. לגבי בקשות files:asyncBatchAnnotate, אפשר להשתמש בסוגי התכונות הבאים:
    • DOCUMENT_TEXT_DETECTION
    • TEXT_DETECTION
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

שיקולים ספציפיים לשדה:

  • ‫inputConfig – מחליף את השדה image שמשמש בבקשות אחרות של Vision API. הוא מכיל שני שדות צאצא:
    • ‫gcsSource.uri – ה-URI של קובץ ה-PDF או ה-TIFF ב-Google Cloud Storage (שהמשתמש או חשבון השירות ששולחים את הבקשה יכולים לגשת אליו).
    • ‫mimeType – אחד מסוגי הקבצים המקובלים: application/pdf או image/tiff.
  • ‫outputConfig – מציין את פרטי הפלט. הוא מכיל שני שדות צאצא:
    • ‫gcsDestination.uri – URI תקין של Cloud Storage. המשתמש או חשבון השירות ששולחים את הבקשה צריכים להיות בעלי הרשאת כתיבה לקטגוריה. שם הקובץ יהיה output-x-to-y, כאשר x ו-y מייצגים את מספרי הדפים ב-PDF או ב-TIFF שכלולים בקובץ הפלט הזה. אם הקובץ קיים, התוכן שלו יידרס.
    • ‫batchSize – מציין כמה דפים של פלט צריך לכלול בכל קובץ JSON של פלט.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate

גוף בקשת JSON: 

{
  "requests":[
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "CLOUD_STORAGE_FILE_URI"
        },
        "mimeType": "application/pdf"
      },
      "features": [
        {
          "type": "FEATURE_TYPE"
        }
      ],
      "outputConfig": {
        "gcsDestination": {
          "uri": "CLOUD_STORAGE_BUCKET"
        },
        "batchSize": 1
      }
    }
  ]
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם 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/files:asyncBatchAnnotate"

PowerShell

שומרים את גוף הבקשה בקובץ בשם 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/files:asyncBatchAnnotate" | Select-Object -Expand Content
תשובה:

בקשת asyncBatchAnnotate מוצלחת מחזירה תגובה עם שדה שם יחיד:

{
  "name": "projects/usable-auth-library/operations/1efec2285bd442df"
}

השם הזה מייצג פעולה ממושכת עם מזהה משויך (לדוגמה, 1efec2285bd442df), שאפשר לשלוח לגביו שאילתה באמצעות v1.operations API.

כדי לאחזר את תגובת ההערה של Vision, שולחים בקשת GET לנקודת הקצה v1.operations ומעבירים את מזהה הפעולה בכתובת ה-URL:

GET https://vision.googleapis.com/v1/operations/operation-id

לדוגמה:

curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df

אם הפעולה מתבצעת:

{
  "name": "operations/1efec2285bd442df",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata",
    "state": "RUNNING",
    "createTime": "2019-05-15T21:10:08.401917049Z",
    "updateTime": "2019-05-15T21:10:33.700763554Z"
  }
}

אחרי שהפעולה תושלם, הסמל state ישתנה ל-DONE והתוצאות ייכתבו לקובץ Google Cloud Storage שציינתם:

{
  "name": "operations/1efec2285bd442df",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata",
    "state": "DONE",
    "createTime": "2019-05-15T20:56:30.622473785Z",
    "updateTime": "2019-05-15T20:56:41.666379749Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse",
    "responses": [
      {
        "outputConfig": {
          "gcsDestination": {
            "uri": "gs://your-bucket-name/folder/"
          },
          "batchSize": 1
        }
      }
    ]
  }
}

ה-JSON בקובץ הפלט דומה ל-JSON של [בקשה לזיהוי טקסט במסמך](/vision/docs/ocr) של תמונה, עם התוספת של השדה context שמציג את המיקום של קובץ ה-PDF או ה-TIFF שצוין ואת מספר הדפים בקובץ:

output-1-to-1.json

Go

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Goהוראות ההגדרה שבמדריך לתחילת העבודה עם Vision באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Vision Go API.

כדי לבצע אימות ב-Vision, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 


// detectAsyncDocumentURI performs Optical Character Recognition (OCR) on a
// PDF file stored in GCS.
func detectAsyncDocumentURI(w io.Writer, gcsSourceURI, gcsDestinationURI string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	request := &visionpb.AsyncBatchAnnotateFilesRequest{
		Requests: []*visionpb.AsyncAnnotateFileRequest{
			{
				Features: []*visionpb.Feature{
					{
						Type: visionpb.Feature_DOCUMENT_TEXT_DETECTION,
					},
				},
				InputConfig: &visionpb.InputConfig{
					GcsSource: &visionpb.GcsSource{Uri: gcsSourceURI},
					// Supported MimeTypes are: "application/pdf" and "image/tiff".
					MimeType: "application/pdf",
				},
				OutputConfig: &visionpb.OutputConfig{
					GcsDestination: &visionpb.GcsDestination{Uri: gcsDestinationURI},
					// How many pages should be grouped into each json output file.
					BatchSize: 2,
				},
			},
		},
	}

	operation, err := client.AsyncBatchAnnotateFiles(ctx, request)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "Waiting for the operation to finish.")

	resp, err := operation.Wait(ctx)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "%v", resp)

	return nil
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java שמפורטות במדריך לתחילת העבודה עם Vision API באמצעות ספריות לקוח. מידע נוסף מופיע ב מאמרי העזרה של Vision API Java.

/**
 * Performs document text OCR with PDF/TIFF as source files on Google Cloud Storage.
 *
 * @param gcsSourcePath The path to the remote file on Google Cloud Storage to detect document
 *     text on.
 * @param gcsDestinationPath The path to the remote file on Google Cloud Storage to store the
 *     results on.
 * @throws Exception on errors while closing the client.
 */
public static void detectDocumentsGcs(String gcsSourcePath, String gcsDestinationPath)
    throws Exception {

  // 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()) {
    List<AsyncAnnotateFileRequest> requests = new ArrayList<>();

    // Set the GCS source path for the remote file.
    GcsSource gcsSource = GcsSource.newBuilder().setUri(gcsSourcePath).build();

    // Create the configuration with the specified MIME (Multipurpose Internet Mail Extensions)
    // types
    InputConfig inputConfig =
        InputConfig.newBuilder()
            .setMimeType(
                "application/pdf") // Supported MimeTypes: "application/pdf", "image/tiff"
            .setGcsSource(gcsSource)
            .build();

    // Set the GCS destination path for where to save the results.
    GcsDestination gcsDestination =
        GcsDestination.newBuilder().setUri(gcsDestinationPath).build();

    // Create the configuration for the System.output with the batch size.
    // The batch size sets how many pages should be grouped into each json System.output file.
    OutputConfig outputConfig =
        OutputConfig.newBuilder().setBatchSize(2).setGcsDestination(gcsDestination).build();

    // Select the Feature required by the vision API
    Feature feature = Feature.newBuilder().setType(Feature.Type.DOCUMENT_TEXT_DETECTION).build();

    // Build the OCR request
    AsyncAnnotateFileRequest request =
        AsyncAnnotateFileRequest.newBuilder()
            .addFeatures(feature)
            .setInputConfig(inputConfig)
            .setOutputConfig(outputConfig)
            .build();

    requests.add(request);

    // Perform the OCR request
    OperationFuture<AsyncBatchAnnotateFilesResponse, OperationMetadata> response =
        client.asyncBatchAnnotateFilesAsync(requests);

    System.out.println("Waiting for the operation to finish.");

    // Wait for the request to finish. (The result is not used, since the API saves the result to
    // the specified location on GCS.)
    List<AsyncAnnotateFileResponse> result =
        response.get(180, TimeUnit.SECONDS).getResponsesList();

    // Once the request has completed and the System.output has been
    // written to GCS, we can list all the System.output files.
    Storage storage = StorageOptions.getDefaultInstance().getService();

    // Get the destination location from the gcsDestinationPath
    Pattern pattern = Pattern.compile("gs://([^/]+)/(.+)");
    Matcher matcher = pattern.matcher(gcsDestinationPath);

    if (matcher.find()) {
      String bucketName = matcher.group(1);
      String prefix = matcher.group(2);

      // Get the list of objects with the given prefix from the GCS bucket
      Bucket bucket = storage.get(bucketName);
      com.google.api.gax.paging.Page<Blob> pageList = bucket.list(BlobListOption.prefix(prefix));

      Blob firstOutputFile = null;

      // List objects with the given prefix.
      System.out.println("Output files:");
      for (Blob blob : pageList.iterateAll()) {
        System.out.println(blob.getName());

        // Process the first System.output file from GCS.
        // Since we specified batch size = 2, the first response contains
        // the first two pages of the input file.
        if (firstOutputFile == null) {
          firstOutputFile = blob;
        }
      }

      // Get the contents of the file and convert the JSON contents to an AnnotateFileResponse
      // object. If the Blob is small read all its content in one request
      // (Note: the file is a .json file)
      // Storage guide: https://cloud.google.com/storage/docs/downloading-objects
      String jsonContents = new String(firstOutputFile.getContent());
      Builder builder = AnnotateFileResponse.newBuilder();
      JsonFormat.parser().merge(jsonContents, builder);

      // Build the AnnotateFileResponse object
      AnnotateFileResponse annotateFileResponse = builder.build();

      // Parse through the object to get the actual response for the first page of the input file.
      AnnotateImageResponse annotateImageResponse = annotateFileResponse.getResponses(0);

      // Here we print the full text from the first page.
      // The response contains more information:
      // annotation/pages/blocks/paragraphs/words/symbols
      // including confidence score and bounding boxes
      System.out.format("%nText: %s%n", annotateImageResponse.getFullTextAnnotation().getText());
    } else {
      System.out.println("No MATCH");
    }
  }
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Node.jsהוראות ההגדרה שבמדריך לתחילת העבודה עם Vision באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Vision Node.js API.

כדי לבצע אימות ב-Vision, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 


// Imports the Google Cloud client libraries
const vision = require('@google-cloud/vision').v1;

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// Bucket where the file resides
// const bucketName = 'my-bucket';
// Path to PDF file within bucket
// const fileName = 'path/to/document.pdf';
// The folder to store the results
// const outputPrefix = 'results'

const gcsSourceUri = `gs://${bucketName}/${fileName}`;
const gcsDestinationUri = `gs://${bucketName}/${outputPrefix}/`;

const inputConfig = {
  // Supported mime_types are: 'application/pdf' and 'image/tiff'
  mimeType: 'application/pdf',
  gcsSource: {
    uri: gcsSourceUri,
  },
};
const outputConfig = {
  gcsDestination: {
    uri: gcsDestinationUri,
  },
};
const features = [{type: 'DOCUMENT_TEXT_DETECTION'}];
const request = {
  requests: [
    {
      inputConfig: inputConfig,
      features: features,
      outputConfig: outputConfig,
    },
  ],
};

const [operation] = await client.asyncBatchAnnotateFiles(request);
const [filesResponse] = await operation.promise();
const destinationUri =
  filesResponse.responses[0].outputConfig.gcsDestination.uri;
console.log('Json saved to: ' + destinationUri);

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה שבמדריך לתחילת העבודה עם Vision באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Vision Python API.

כדי לבצע אימות ב-Vision, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

def async_detect_document(gcs_source_uri, gcs_destination_uri):
    """OCR with PDF/TIFF as source files on GCS"""
    import json
    import re
    from google.cloud import vision
    from google.cloud import storage

    # Supported mime_types are: 'application/pdf' and 'image/tiff'
    mime_type = "application/pdf"

    # How many pages should be grouped into each json output file.
    batch_size = 2

    client = vision.ImageAnnotatorClient()

    feature = vision.Feature(type_=vision.Feature.Type.DOCUMENT_TEXT_DETECTION)

    gcs_source = vision.GcsSource(uri=gcs_source_uri)
    input_config = vision.InputConfig(gcs_source=gcs_source, mime_type=mime_type)

    gcs_destination = vision.GcsDestination(uri=gcs_destination_uri)
    output_config = vision.OutputConfig(
        gcs_destination=gcs_destination, batch_size=batch_size
    )

    async_request = vision.AsyncAnnotateFileRequest(
        features=[feature], input_config=input_config, output_config=output_config
    )

    operation = client.async_batch_annotate_files(requests=[async_request])

    print("Waiting for the operation to finish.")
    operation.result(timeout=420)

    # Once the request has completed and the output has been
    # written to GCS, we can list all the output files.
    storage_client = storage.Client()

    match = re.match(r"gs://([^/]+)/(.+)", gcs_destination_uri)
    bucket_name = match.group(1)
    prefix = match.group(2)

    bucket = storage_client.get_bucket(bucket_name)

    # List objects with the given prefix, filtering out folders.
    blob_list = [
        blob
        for blob in list(bucket.list_blobs(prefix=prefix))
        if not blob.name.endswith("/")
    ]
    print("Output files:")
    for blob in blob_list:
        print(blob.name)

    # Process the first output file from GCS.
    # Since we specified batch_size=2, the first response contains
    # the first two pages of the input file.
    output = blob_list[0]

    json_string = output.download_as_bytes().decode("utf-8")
    response = json.loads(json_string)

    # The actual response for the first page of the input file.
    first_page_response = response["responses"][0]
    annotation = first_page_response["fullTextAnnotation"]

    # Here we print the full text from the first page.
    # The response contains more information:
    # annotation/pages/blocks/paragraphs/words/symbols
    # including confidence scores and bounding boxes
    print("Full text:\n")
    print(annotation["text"])

gcloud

הפקודה gcloud שבה משתמשים תלויה בסוג הקובץ.

  • כדי לבצע זיהוי טקסט ב-PDF, משתמשים בפקודה gcloud ml vision detect-text-pdf כמו בדוגמה הבאה:

    gcloud ml vision detect-text-pdf gs://my_bucket/input_file  gs://my_bucket/out_put_prefix

  • כדי לבצע זיהוי טקסט בפורמט TIFF, משתמשים בפקודה gcloud ml vision detect-text-tiff כמו בדוגמה הבאה:

    gcloud ml vision detect-text-tiff gs://my_bucket/input_file  gs://my_bucket/out_put_prefix

שפות נוספות

‫C#‎: צריך לפעול לפי הוראות ההגדרה של C# ‎ בדף של ספריות הלקוח ואז לעבור אל מאמרי העזרה של Vision בנושא ‎ .NET.

‫PHP: Please follow the PHP setup instructions on the client libraries page and then visit the Vision מאמרי עזרה for PHP.

‫Ruby: צריך לפעול לפי הוראות ההגדרה של Ruby בדף של ספריות הלקוח ואז לעיין במאמרי העזרה של Vision בנושא Ruby.

תמיכה במספר אזורים

עכשיו אפשר לציין אחסון נתונים ועיבוד OCR ברמת היבשת. נכון לעכשיו, האזורים הבאים נתמכים:

  • ‫us: ארה"ב בלבד
  • ‫eu: האיחוד האירופי

מיקומים

‫Cloud Vision מאפשר לכם לקבוע איפה המשאבים של הפרויקט יאוחסנו ויעובדו. בפרט, אתם יכולים להגדיר את Cloud Vision כך שיאחסן ויעבד את הנתונים שלכם רק באיחוד האירופי.

כברירת מחדל, Cloud Vision מאחסן ומעבד משאבים במיקום גלובלי, כלומר Cloud Vision לא מבטיח שהמשאבים יישארו במיקום או באזור מסוימים. אם תבחרו במיקום האיחוד האירופי, Google תאחסן את הנתונים שלכם ותעבד אותם רק באיחוד האירופי. אתם והמשתמשים שלכם יכולים לגשת לנתונים מכל מקום.

הגדרת המיקום באמצעות ה-API

‫Vision API תומך בנקודת קצה ל-API גלובלית (vision.googleapis.com) וגם בשתי נקודות קצה שמבוססות על אזורים: נקודת קצה של האיחוד האירופי (eu-vision.googleapis.com) ונקודת קצה של ארצות הברית (us-vision.googleapis.com). כדאי להשתמש בנקודות הקצה האלה לעיבוד נתונים שספציפיים לאזור. לדוגמה, כדי לאחסן ולעבד את הנתונים שלכם באיחוד האירופי בלבד, צריך להשתמש ב-URI eu-vision.googleapis.com במקום vision.googleapis.com בשיחות API בארכיטקטורת REST:

  • 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: אחד ממזהי המיקום האזוריים התקפים:
    • ‫us: ארה"ב בלבד
    • ‫eu: האיחוד האירופי
  • ‫CLOUD_STORAGE_IMAGE_URI: הנתיב לקובץ תמונה תקין בקטגוריה של Cloud Storage. צריכות להיות לכם לפחות הרשאות קריאה לקובץ. דוגמה: 
    • gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
  • ‫CLOUD_STORAGE_BUCKET: קטגוריה או ספרייה ב-Cloud Storage לשמירת קובצי הפלט, בפורמט הבא:
    • gs://bucket/directory/
    למשתמש ששולח את הבקשה צריכה להיות הרשאת כתיבה לקטגוריה.
  • FEATURE_TYPE: סוג תכונה תקין. לגבי בקשות files:asyncBatchAnnotate, אפשר להשתמש בסוגי התכונות הבאים:
    • DOCUMENT_TEXT_DETECTION
    • TEXT_DETECTION
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

שיקולים ספציפיים לשדה:

  • ‫inputConfig – מחליף את השדה image שמשמש בבקשות אחרות של Vision API. הוא מכיל שני שדות צאצא:
    • ‫gcsSource.uri – ה-URI של קובץ ה-PDF או ה-TIFF ב-Google Cloud Storage (שהמשתמש או חשבון השירות ששולחים את הבקשה יכולים לגשת אליו).
    • ‫mimeType – אחד מסוגי הקבצים המקובלים: application/pdf או image/tiff.
  • ‫outputConfig – מציין את פרטי הפלט. הוא מכיל שני שדות צאצא:
    • ‫gcsDestination.uri – URI תקין של Cloud Storage. המשתמש או חשבון השירות ששולחים את הבקשה צריכים להיות בעלי הרשאת כתיבה לקטגוריה. שם הקובץ יהיה output-x-to-y, כאשר x ו-y מייצגים את מספרי הדפים ב-PDF או ב-TIFF שכלולים בקובץ הפלט הזה. אם הקובץ קיים, התוכן שלו יידרס.
    • ‫batchSize – מציין כמה דפים של פלט צריך לכלול בכל קובץ JSON של פלט.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate

גוף בקשת JSON: 

{
  "requests":[
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "CLOUD_STORAGE_IMAGE_URI"
        },
        "mimeType": "application/pdf"
      },
      "features": [
        {
          "type": "FEATURE_TYPE"
        }
      ],
      "outputConfig": {
        "gcsDestination": {
          "uri": "CLOUD_STORAGE_BUCKET"
        },
        "batchSize": 1
      }
    }
  ]
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם 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/files:asyncBatchAnnotate"

PowerShell

שומרים את גוף הבקשה בקובץ בשם 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/files:asyncBatchAnnotate" | Select-Object -Expand Content
תשובה:

בקשת asyncBatchAnnotate מוצלחת מחזירה תגובה עם שדה שם יחיד:

{
  "name": "projects/usable-auth-library/operations/1efec2285bd442df"
}

השם הזה מייצג פעולה ממושכת עם מזהה משויך (לדוגמה, 1efec2285bd442df), שאפשר לשלוח לגביו שאילתה באמצעות v1.operations API.

כדי לאחזר את תגובת ההערה של Vision, שולחים בקשת GET לנקודת הקצה v1.operations ומעבירים את מזהה הפעולה בכתובת ה-URL:

GET https://vision.googleapis.com/v1/operations/operation-id

לדוגמה:

curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df

אם הפעולה מתבצעת:

{
  "name": "operations/1efec2285bd442df",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata",
    "state": "RUNNING",
    "createTime": "2019-05-15T21:10:08.401917049Z",
    "updateTime": "2019-05-15T21:10:33.700763554Z"
  }
}

אחרי שהפעולה תושלם, הסמל state ישתנה ל-DONE והתוצאות ייכתבו לקובץ Google Cloud Storage שציינתם:

{
  "name": "operations/1efec2285bd442df",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata",
    "state": "DONE",
    "createTime": "2019-05-15T20:56:30.622473785Z",
    "updateTime": "2019-05-15T20:56:41.666379749Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse",
    "responses": [
      {
        "outputConfig": {
          "gcsDestination": {
            "uri": "gs://your-bucket-name/folder/"
          },
          "batchSize": 1
        }
      }
    ]
  }
}

ה-JSON בקובץ הפלט דומה ל-JSON של תגובת זיהוי טקסט במסמך של תמונה אם השתמשתם בתכונה DOCUMENT_TEXT_DETECTION, או לתגובת זיהוי טקסט אם השתמשתם בתכונה TEXT_DETECTION. בפלט יופיע שדה נוסף context עם המיקום של קובץ ה-PDF או ה-TIFF שצוין ומספר הדפים בקובץ:

output-1-to-1.json

Go

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Goהוראות ההגדרה שבמדריך לתחילת העבודה עם Vision באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Vision Go API.

כדי לבצע אימות ב-Vision, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java שמפורטות במדריך לתחילת העבודה עם Vision API באמצעות ספריות לקוח. מידע נוסף מופיע ב מאמרי העזרה של Vision API Java.

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, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

// 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, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

from google.cloud import vision

client_options = {"api_endpoint": "eu-vision.googleapis.com"}

client = vision.ImageAnnotatorClient(client_options=client_options)

נסו בעצמכם

אנחנו ממליצים למשתמשים חדשים ב-Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של Cloud Vision API בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300 $להרצה, לבדיקה ולפריסה של עומסי העבודה.

ניסיון חינם של Cloud Vision API