‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שליחת בקשות באצווה

במאמר הזה נסביר איך לקבץ באצווה קריאות ל-API בפורמט JSON כדי לצמצם את מספר חיבורי ה-HTTP שהלקוח צריך לבצע בשביל גישה ל-Cloud Storage.

סקירה כללית של בקשות באצווה

כל חיבור HTTP שהלקוח יוצר מגדיל במידה מסוימת את התקורה. ה-API בפורמט JSON של Cloud Storage תומך בקיבוץ באצווה של בקשות, כדי לאפשר ללקוח לקבץ מספר קריאות ל-API בבקשת HTTP אחת. כשמקבצים כמה קריאות ל-API לבקשה אחת, אפשר לצמצם את התקורה ואת זמן האחזור ברשת כשצריך לבצע הרבה פעולות.

דוגמאות לפעולות שכדאי להשתמש בהן בבקשות באצווה:

עדכון מטא-נתונים, כמו הרשאות, באובייקטים רבים
מחיקת אובייקטים רבים

‫Cloud Storage לא תומך בפעולות באצווה להעלאה ולהורדה.

מבנה של בקשת Batch

בקשת Batch היא בקשת HTTP רגילה אחת שמכילה מספר קריאות ל-API בפורמט JSON של Cloud Storage. הבקשה החיצונית של בקשת Batch משתמשת ב-multipart/mixed ב-request header Content-Type, עם גוף שמורכב מכמה חלקים שכל אחד מהם מכיל בקשת משנה נפרדת של HTTP.

בקשת ה-Batch החיצונית נשלחת לנקודת הקצה של ה-Batch:

https://storage./batch/storage/v1

כל בקשת משנה בגוף הבקשה באצווה מציינת נתיב בקשה רגיל של API בפורמט JSON של Cloud Storage, כמו:

https://storage./storage/v1/BUCKET_NAME/o/OBJECT_NAME

כדי לראות את הפורמט של בקשת Batch לדוגמה, אפשר לעיין בדוגמה.

כדי להימנע משגיאות HTTP 400, מפסקי זמן של שערים ומניתוקים, לא מומלץ לכלול יותר מ-100 קריאות בבקשת Batch אחת. אם צריך לבצע יותר מ-100 קריאות, תוכלו להשתמש במספר בקשות באצווה. המטען הייעודי (payload) הכולל של בקשות באצווה צריך להיות קטן מ-10MB. בקשות גדולות יותר נדחות על ידי Cloud Storage.

הפורמט של בקשת Batch

בקטע הזה מתואר הפורמט של בקשת Batch.

בגוף של הבקשה החיצונית, כל חלק מתחיל בכותרת HTTP ‏Content-Type: application/http משלו. לחלק יכולה להיות גם כותרת Content-ID אופציונלית. הכותרות האלה מציינות את תחילת החלק, אבל הן נפרדות מבקשת ה-HTTP הפנימית. המשמעות היא שאחרי שהשרת מפרק את בקשת Batch לבקשות נפרדות, המערכת מתעלמת מכותרות החלקים.

הגוף של כל חלק הוא בעצמו בקשת HTTP מלאה עם פועל, כתובת URL, כותרות וגוף. בקשות ה-HTTP צריכות להכיל רק את החלק של הנתיב שבכתובת ה-URL; ההתנהגות של כתובות URL מלאות עלולה להיות לא צפויה.

כותרות ה-HTTP של בקשת Batch החיצונית חלות גם על כל בקשה פנימית שבתוך בקשת Batch, מלבד כותרות Content- כמו Content-Type. עם זאת, אם מציינים כותרת HTTP ספציפית בבקשת Batch החיצונית וגם בבקשה פנימית, ערך הכותרת של הבקשה הפנימית מבטל את ערך הכותרת של בקשת Batch החיצונית בבקשה הספציפית הזו.

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

כש-Cloud Storage מקבל את הבקשה באצווה, המערכת מחילה את הפרמטרים והכותרות של השאילתה החיצונית (לפי הכללים) על כל חלק, ולאחר מכן מתייחסת לכל חלק כאילו היה בקשת HTTP נפרדת.

תשובה לבקשת Batch

התשובה ב-Cloud Storage היא תשובת HTTP רגילה יחידה עם סוג תוכן multipart/mixed. כל חלק בתגובה הראשית הזו הוא תשובה לאחת מהבקשות שבבקשה באצווה. סדר התשובות זהה לסדר הבקשות.

כמו החלקים בבקשה, כל חלק בתשובה מכיל תשובת HTTP מלאה הכוללת קוד סטטוס, כותרות וגוף. בדומה לחלקים שבבקשה, לפני כל חלק של תשובה מופיעה כותרת Content-Type שמסמנת את תחילת החלק. מידע נוסף על קודי סטטוס אפשר למצוא במאמר בנושא קודי סטטוס ושגיאה של HTTP ב-API בפורמט JSON של Cloud Storage.

אם לחלק מסוים בבקשה יש כותרת Content-ID, לחלק המתאים בתשובה יש כותרת Content-ID תואמת. הכותרת Content-ID של התשובה מתחילה ב-response-, ואחריו הערך Content-ID שנמצא בשימוש בבקשה, כפי שמוצג בדוגמה.

דוגמה

בדוגמה הבאה הקריאה באצווה מעדכנת את המטא-נתונים המותאמים אישית של שלושה אובייקטים ב-example-bucket.

דוגמה לבקשת HTTP באצווה

HTTP

POST /batch/storage/v1 HTTP/1.1
Host: storage.
Content-Length: 960
Content-Type: multipart/mixed; boundary="===============7330845974216740156=="
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+1>

PATCH /storage/v1/b/example-bucket/o/obj1 HTTP/1.1
Content-Type: application/json
accept: application/json
content-length: 31

{"metadata": {"type": "tabby"}}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+2>

PATCH /storage/v1/b/example-bucket/o/obj2 HTTP/1.1
Content-Type: application/json
accept: application/json
content-length: 32

{"metadata": {"type": "tuxedo"}}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+3>

PATCH /storage/v1/b/example-bucket/o/obj3 HTTP/1.1
Content-Type: application/json
accept: application/json
content-length: 32

{"metadata": {"type": "calico"}}
--===============7330845974216740156==--

ספריות לקוח

C++‎

ספריית הלקוח C++‎ לא תומכת בבקשות באצווה.

C#‎

ספריית הלקוח C#‎ לא תומכת בבקשות באצווה.

Go

ספריית הלקוח Go לא תומכת בבקשות באצווה.

Java

מידע נוסף מופיע במאמרי העזרה של Cloud Storage Java API.

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageBatch;
import com.google.cloud.storage.StorageBatchResult;
import com.google.cloud.storage.StorageException;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.stream.Collectors;

public class BatchSetObjectMetadata {
  public static void batchSetObjectMetadata(
      String projectId, String bucketName, String pathPrefix) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The directory prefix. All objects in the bucket with this prefix will have their metadata
    // updated
    // String pathPrefix = "yourPath/";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Map<String, String> newMetadata = new HashMap<>();
    newMetadata.put("keyToAddOrUpdate", "value");
    Page<Blob> blobs =
        storage.list(
            bucketName,
            Storage.BlobListOption.prefix(pathPrefix),
            Storage.BlobListOption.delimiter("/"));
    StorageBatch batchRequest = storage.batch();

    // Add all blobs with the given prefix to the batch request
    List<StorageBatchResult<Blob>> batchResults =
        blobs
            .streamAll()
            .map(blob -> batchRequest.update(blob.toBuilder().setMetadata(newMetadata).build()))
            .collect(Collectors.toList());

    // Execute the batch request
    batchRequest.submit();
    List<StorageException> failures =
        batchResults.stream()
            .map(
                r -> {
                  try {
                    BlobInfo blob = r.get();
                    return null;
                  } catch (StorageException e) {
                    return e;
                  }
                })
            .filter(Objects::nonNull)
            .collect(Collectors.toList());

    System.out.println(
        (batchResults.size() - failures.size())
            + " blobs in bucket "
            + bucketName
            + " with prefix '"
            + pathPrefix
            + "' had their metadata updated successfully.");

    if (!failures.isEmpty()) {
      System.out.println("While processing, there were " + failures.size() + " failures");

      for (StorageException failure : failures) {
        failure.printStackTrace(System.out);
      }
    }
  }
}

Node.js

ספריית הלקוח Node.js לא תומכת בבקשות באצווה.

PHP

ספריית הלקוח PHP לא תומכת בבקשות באצווה.

Python

מידע נוסף מופיע במאמרי העזרה של Cloud Storage Python API.


from google.cloud import storage


def batch_request(bucket_name, prefix=None):
    """
    Use a batch request to patch a list of objects with the given prefix in a bucket.

    Note that Cloud Storage does not support batch operations for uploading or downloading.
    Additionally, the current batch design does not support library methods whose return values
    depend on the response payload.
    See https://cloud.google.com/python/docs/reference/storage/latest/google.cloud.storage.batch
    """
    # The ID of your GCS bucket
    # bucket_name = "my-bucket"
    # The prefix of the object paths
    # prefix = "directory-prefix/"

    client = storage.Client()
    bucket = client.bucket(bucket_name)

    # Accumulate in a list the objects with a given prefix.
    blobs_to_patch = [blob for blob in bucket.list_blobs(prefix=prefix)]

    # Use a batch context manager to edit metadata in the list of blobs.
    # The batch request is sent out when the context manager closes.
    # No more than 100 calls should be included in a single batch request.
    with client.batch():
        for blob in blobs_to_patch:
            metadata = {"your-metadata-key": "your-metadata-value"}
            blob.metadata = metadata
            blob.patch()

    print(
        f"Batch request edited metadata for all objects with the given prefix in {bucket.name}."
    )

Ruby

מידע נוסף על שליחת בקשת Batch באמצעות Ruby מופיע במאמרי העזרה של ה-API של Cloud Storage Ruby.

חלודה

ספריית הלקוח Rust לא תומכת בבקשות באצווה.

דוגמה לתשובת HTTP באצווה

זוהי התשובה לבקשת ה-HTTP מהדוגמה שבקטע הקודם.

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 3767

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+1>

HTTP/1.1 200 OK
ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/V43j6azD55CPRGb9b6uytDYl61Y"
Content-Type: application/json; charset=UTF-8
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 846

{
 "kind": "storage#object",
 "id": "example-bucket/obj1/1495822576643790",
 .
 .
 .
 "metadata": {
  "type": "tabby"
  },
  .
  .
  .
}

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+2>

HTTP/1.1 200 OK
ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/91POdd-sxSAkJnS8Dm7wMxBSDKk"
Content-Type: application/json; charset=UTF-8
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 846

{
 "kind": "storage#object",
 "id": "example-bucket/obj2/1495822576643790",
 .
 .
 .
 "metadata": {
  "type": "tuxedo"
  },
  .
  .
  .
}

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+3>

HTTP/1.1 200 OK
ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/d2Z1F1_ZVbB1dC0YKM9rX5VAgIQ"
Content-Type: application/json; charset=UTF-8
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 846

{
 "kind": "storage#object",
 "id": "example-bucket/obj3/1495822576643790",
 .
 .
 .
 "metadata": {
  "type": "calico"
  },
  .
  .
  .
}

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--

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

כשהבקשה הכוללת מוחזרת עם קוד הסטטוס 200, התשובה כוללת תוצאות לכל בקשת משנה, כולל קוד סטטוס לכל אחת, שמציין אם בקשת המשנה הצליחה או נכשלה. לדוגמה, כשמוחקים אובייקטים בקבוצה, כל בקשת משנה שמושלמת בהצלחה מכילה קוד סטטוס 204 No Content.