קריאת אובייקטים

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

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

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לקריאת נתוני אובייקטים, בקשו מהאדמין לתת לכם את התפקידים הבאים ב-IAM:

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

התפקיד "צפייה באובייקט אחסון" (roles/storage.objectViewer) כולל את ההרשאה storage.objects.get, שנדרשת כדי לקרוא אובייקטים. התפקיד Storage Admin ‏ (roles/storage.admin) מכיל את ההרשאות storage.buckets.list ו-storage.buckets.get, בנוסף להרשאה storage.objects.get. ההרשאות האלה נדרשות כדי להציג את רשימת הקטגוריות בפרויקט ומידע על הקטגוריות. התפקיד "אדמין של Storage" (roles/storage.admin) שכולל את ההרשאות האלה נדרש רק כשרוצים לקרוא אובייקטים באופן אינטראקטיבי באמצעות מסוף Google Cloud .

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

במאמר הגדרה וניהול של מדיניות IAM בקטגוריות מוסבר איך מקצים תפקידים בקטגוריות.

קריאת אובייקטים לזיכרון באופן פרוגרמטי

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

ספריות לקוח

C++

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage C++ API.

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

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  gcs::ObjectReadStream stream = client.ReadObject(bucket_name, object_name);
  std::string buffer{std::istreambuf_iterator<char>(stream),
                     std::istreambuf_iterator<char>()};
  if (stream.bad()) throw google::cloud::Status(stream.status());

  std::cout << "The object has " << buffer.size() << " characters\n";
}

C#

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage C# API.

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


using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class DownloadObjectIntoMemorySample
{
    public Stream DownloadObjectIntoMemory(
        string bucketName = "unique-bucket-name",
        string objectName = "file-name")
    {
        var storage = StorageClient.Create();
        Stream stream = new MemoryStream();
        storage.DownloadObject(bucketName, objectName, stream);

        Console.WriteLine($"The contents of {objectName} from bucket {bucketName} are downloaded");
        return stream;
    }
}

Go

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Go API.

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


import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// downloadFileIntoMemory downloads an object.
func downloadFileIntoMemory(w io.Writer, bucket, object string) ([]byte, error) {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	rc, err := client.Bucket(bucket).Object(object).NewReader(ctx)
	if err != nil {
		return nil, fmt.Errorf("Object(%q).NewReader: %w", object, err)
	}
	defer rc.Close()

	data, err := io.ReadAll(rc)
	if err != nil {
		return nil, fmt.Errorf("io.ReadAll: %w", err)
	}
	fmt.Fprintf(w, "Blob %v downloaded.\n", object)
	return data, nil
}

Java

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Java API.

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


import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.nio.charset.StandardCharsets;

public class DownloadObjectIntoMemory {
  public static void downloadObjectIntoMemory(
      String projectId, String bucketName, String objectName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The ID of your GCS object
    // String objectName = "your-object-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    byte[] content = storage.readAllBytes(bucketName, objectName);
    System.out.println(
        "The contents of "
            + objectName
            + " from bucket name "
            + bucketName
            + " are: "
            + new String(content, StandardCharsets.UTF_8));
  }
}

Node.js

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Node.js API.

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function downloadIntoMemory() {
  // Downloads the file into a buffer in memory.
  const contents = await storage.bucket(bucketName).file(fileName).download();

  console.log(
    `Contents of gs://${bucketName}/${fileName} are ${contents.toString()}.`
  );
}

downloadIntoMemory().catch(console.error);

PHP

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage PHP API.

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

use Google\Cloud\Storage\StorageClient;

/**
 * Download an object from Cloud Storage and save into a buffer in memory.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function download_object_into_memory(
    string $bucketName,
    string $objectName
): void {
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $contents = $object->downloadAsString();
    printf(
        'Downloaded %s from gs://%s/%s' . PHP_EOL,
        $contents,
        $bucketName,
        $objectName
    );
}

Python

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Python API.

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

from google.cloud import storage


def download_blob_into_memory(bucket_name, blob_name):
    """Downloads a blob into memory."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your GCS object
    # blob_name = "storage-object-name"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(blob_name)
    contents = blob.download_as_bytes()

    print(
        "Downloaded storage object {} from bucket {} as the following bytes object: {}.".format(
            blob_name, bucket_name, contents.decode("utf-8")
        )
    )

Ruby

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Ruby API.

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

# The name of the bucket to access
# bucket_name = "my-bucket"

# The name of the remote file to download
# file_name = "file.txt"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name, skip_lookup: true
file    = bucket.file file_name

downloaded = file.download
downloaded.rewind # Optional - not needed on first read
contents = downloaded.read

puts "Contents of storage object #{file.name} in bucket #{bucket_name} are: #{contents}"

Rust

use google_cloud_storage::client::Storage;

pub async fn sample(client: &Storage, bucket: &str) -> Result<(), anyhow::Error> {
    const NAME: &str = "object-to-download.txt";
    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket}"), NAME)
        .send()
        .await?;

    let mut content = Vec::new();
    while let Some(data) = reader.next().await.transpose()? {
        content.extend_from_slice(&data);
    }

    println!(
        "Downloaded {} bytes of object {NAME} in bucket {bucket}.",
        content.len()
    );
    Ok(())
}

קריאת אובייקטים באופן אינטראקטיבי

בקטע הזה מוסבר איך לקרוא אובייקטים באופן אינטראקטיבי בGoogle Cloud חלון הדפדפן של המסוף או בטרמינל של שורת הפקודה stdout.

המסוף

  1. במסוף Google Cloud , נכנסים לדף Buckets של Cloud Storage.

    כניסה לדף Buckets

  2. ברשימת הקטגוריות, לוחצים על השם של הקטגוריה שאת התוכן שלה רוצים לראות.

  3. בכרטיסייה Objects, לוחצים על שם האובייקט שרוצים לקרוא.

  4. בדף Object details, לוחצים על כתובת ה-URL הציבורית או על כתובת ה-URL המאומתת של האובייקט כדי לקרוא את הנתונים שלו.

שורת הפקודה

כדי להעביר בסטרימינג את המטען הייעודי (payload) של אובייקט בבייטים ישירות לטרמינל stdout, משתמשים בפקודה gcloud storage cat:

gcloud storage cat gs://BUCKET_NAME/OBJECT_NAME

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

  • ‫BUCKET_NAME: שם הקטגוריה שמכילה את האובייקט שרוצים לקרוא. לדוגמה, my-bucket.

  • ‫OBJECT_NAME: שם האובייקט שרוצים לקרוא. לדוגמה, dog.png.

ממשקי API בארכיטקטורת REST

כדי לקרוא את הבייטים של אובייקט ולהפנות את זרם הפלט למסוף stdout, פועלים לפי ההוראות הבאות.

‫API בפורמט JSON

  1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

  2. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת objects.get שכוללת את האפשרות -o - ואת הפרמטר של השאילתה alt=media:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-o - \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"

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

    • ‫BUCKET_NAME: שם הקטגוריה שמכילה את האובייקט שרוצים לקרוא. לדוגמה, my-bucket.

    • ‫OBJECT_NAME: השם של האובייקט שרוצים לקרוא, בקידודי תווים שמתאימים לכתובות URL. לדוגמה, pets/dog.png יותאם לקידודי התווים שמתאימים לכתובות URL באופן הבא: pets%2Fdog.png.

‫API בפורמט XML

  1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

  2. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט XML באמצעות בקשת אובייקט GET:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

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

    • ‫BUCKET_NAME: שם הקטגוריה שמכילה את האובייקט שרוצים לקרוא. לדוגמה, my-bucket.

    • ‫OBJECT_NAME: השם של האובייקט שרוצים לקרוא, בקידודי תווים שמתאימים לכתובות URL. לדוגמה, pets/dog.png יותאם לקידודי התווים שמתאימים לכתובות URL באופן הבא: pets%2Fdog.png.

המאמרים הבאים