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

הצגת רשימה של אובייקטים

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

לפני שמתחילים

כדי לקבל את ההרשאות שדרושות להצגה של רשימת אובייקטים, צריך לבקש מהאדמין להקצות לכם את התפקיד "צפייה באובייקט אחסון" (roles/storage.objectViewer) ב-IAM בקטגוריה שכוללת את האובייקטים שאתם רוצים להציג ברשימה. אם רוצים להציג רשימה של אובייקטים בתיקיות מנוהלות, אפשר להעניק הרשאת roles/storage.objectViewer לתיקייה המנוהלת שמכילה את האובייקטים שרוצים לראות במקום לקטגוריה.

אם אתם מתכננים להשתמש במסוף Google Cloud כדי לבצע את המשימות שבדף הזה, בקשו מהאדמין להקצות לכם את התפקיד הבסיסי "צפייה" (roles/viewer) בנוסף לתפקיד "צפייה באובייקט אחסון" (roles/storage.objectViewer).

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

ההרשאות הנדרשות

storage.objects.list
storage.buckets.list
- ההרשאה הזו נדרשת רק אם רוצים להשתמש ב Google Cloud מסוף כדי לבצע את המשימות שבדף הזה.

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

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

הצגת רשימה של האובייקטים בקטגוריה

המסוף

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

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

שורת הפקודה

משתמשים בפקודה gcloud storage ls:

gcloud storage ls gs://BUCKET_NAME

כאשר:

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

ספריות לקוח

C++

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

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

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name) {
  for (auto&& object_metadata : client.ListObjects(bucket_name)) {
    if (!object_metadata) throw std::move(object_metadata).status();

    std::cout << "bucket_name=" << object_metadata->bucket()
              << ", object_name=" << object_metadata->name() << "\n";
  }
}

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& bucket_prefix) {
  for (auto&& object_metadata :
       client.ListObjects(bucket_name, gcs::Prefix(bucket_prefix))) {
    if (!object_metadata) throw std::move(object_metadata).status();

    std::cout << "bucket_name=" << object_metadata->bucket()
              << ", object_name=" << object_metadata->name() << "\n";
  }
}

C#

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

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

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:


using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class ListFilesSample
{
    public IEnumerable<Google.Apis.Storage.v1.Data.Object> ListFiles(
        string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var storageObjects = storage.ListObjects(bucketName);
        Console.WriteLine($"Files in bucket {bucketName}:");
        foreach (var storageObject in storageObjects)
        {
            Console.WriteLine(storageObject.Name);
        }

        return storageObjects;
    }
}

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:


using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class ListFilesWithPrefixSample
{
    /// <summary>
    /// Prefixes and delimiters can be used to emulate directory listings.
    /// Prefixes can be used to filter objects starting with prefix.
    /// The delimiter argument can be used to restrict the results to only the
    /// objects in the given "directory". Without the delimiter, the entire  tree
    /// under the prefix is returned.
    /// For example, given these objects:
    ///   a/1.txt
    ///   a/b/2.txt
    ///
    /// If you just specify prefix="a/", you'll get back:
    ///   a/1.txt
    ///   a/b/2.txt
    ///
    /// However, if you specify prefix="a/" and delimiter="/", you'll get back:
    ///   a/1.txt
    /// </summary>
    /// <param name="bucketName">The bucket to list the objects from.</param>
    /// <param name="prefix">The prefix to match. Only objects with names that start with this string will
    /// be returned. This parameter may be null or empty, in which case no filtering
    /// is performed.</param>
    /// <param name="delimiter">Used to list in "directory mode". Only objects whose names (aside from the prefix)
    /// do not contain the delimiter will be returned.</param>
    public IEnumerable<Google.Apis.Storage.v1.Data.Object> ListFilesWithPrefix(
        string bucketName = "your-unique-bucket-name",
        string prefix = "your-prefix",
        string delimiter = "your-delimiter")
    {
        var storage = StorageClient.Create();
        var options = new ListObjectsOptions { Delimiter = delimiter };
        var storageObjects = storage.ListObjects(bucketName, prefix, options);
        Console.WriteLine($"Objects in bucket {bucketName} with prefix {prefix}:");
        foreach (var storageObject in storageObjects)
        {
            Console.WriteLine(storageObject.Name);
        }
        return storageObjects;
    }
}

Go

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

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

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:

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

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// listFiles lists objects within specified bucket.
func listFiles(w io.Writer, bucket string) error {
	// bucket := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

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

	it := client.Bucket(bucket).Objects(ctx, nil)
	for {
		attrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("Bucket(%q).Objects: %w", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name)
	}
	return nil
}

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

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

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// listFilesWithPrefix lists objects using prefix and delimeter.
func listFilesWithPrefix(w io.Writer, bucket, prefix, delim string) error {
	// bucket := "bucket-name"
	// prefix := "/foo"
	// delim := "_"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Prefixes and delimiters can be used to emulate directory listings.
	// Prefixes can be used to filter objects starting with prefix.
	// The delimiter argument can be used to restrict the results to only the
	// objects in the given "directory". Without the delimiter, the entire tree
	// under the prefix is returned.
	//
	// For example, given these blobs:
	//   /a/1.txt
	//   /a/b/2.txt
	//
	// If you just specify prefix="a/", you'll get back:
	//   /a/1.txt
	//   /a/b/2.txt
	//
	// However, if you specify prefix="a/" and delim="/", you'll get back:
	//   /a/1.txt
	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	it := client.Bucket(bucket).Objects(ctx, &storage.Query{
		Prefix:    prefix,
		Delimiter: delim,
	})
	for {
		attrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("Bucket(%q).Objects(): %w", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name)
	}
	return nil
}

Java

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

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

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

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

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

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Page<Blob> blobs = storage.list(bucketName);

    for (Blob blob : blobs.iterateAll()) {
      System.out.println(blob.getName());
    }
  }
}

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ListObjectsWithPrefix {
  public static void listObjectsWithPrefix(
      String projectId, String bucketName, String directoryPrefix) {
    // 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 to search for
    // String directoryPrefix = "myDirectory/"

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    /**
     * Using the Storage.BlobListOption.currentDirectory() option here causes the results to display
     * in a "directory-like" mode, showing what objects are in the directory you've specified, as
     * well as what other directories exist in that directory. For example, given these blobs:
     *
     * <p>a/1.txt a/b/2.txt a/b/3.txt
     *
     * <p>If you specify prefix = "a/" and don't use Storage.BlobListOption.currentDirectory(),
     * you'll get back:
     *
     * <p>a/1.txt a/b/2.txt a/b/3.txt
     *
     * <p>However, if you specify prefix = "a/" and do use
     * Storage.BlobListOption.currentDirectory(), you'll get back:
     *
     * <p>a/1.txt a/b/
     *
     * <p>Because a/1.txt is the only file in the a/ directory and a/b/ is a directory inside the
     * /a/ directory.
     */
    Page<Blob> blobs =
        storage.list(
            bucketName,
            Storage.BlobListOption.prefix(directoryPrefix),
            Storage.BlobListOption.currentDirectory());

    for (Blob blob : blobs.iterateAll()) {
      System.out.println(blob.getName());
    }
  }
}

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';

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

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

async function listFiles() {
  // Lists files in the bucket
  const [files] = await storage.bucket(bucketName).getFiles();

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name);
  });
}

listFiles().catch(console.error);

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

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

// The directory prefix to search for
// const prefix = 'myDirectory/';

// The delimiter to use
// const delimiter = '/';

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

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

async function listFilesByPrefix() {
  /**
   * This can be used to list all blobs in a "folder", e.g. "public/".
   *
   * The delimiter argument can be used to restrict the results to only the
   * "files" in the given "folder". Without the delimiter, the entire tree under
   * the prefix is returned. For example, given these blobs:
   *
   *   /a/1.txt
   *   /a/b/2.txt
   *
   * If you just specify prefix = 'a/', you'll get back:
   *
   *   /a/1.txt
   *   /a/b/2.txt
   *
   * However, if you specify prefix='a/' and delimiter='/', you'll get back:
   *
   *   /a/1.txt
   */
  const options = {
    prefix: prefix,
  };

  if (delimiter) {
    options.delimiter = delimiter;
  }

  // Lists files in the bucket, filtered by a prefix
  const [files] = await storage.bucket(bucketName).getFiles(options);

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name);
  });
}

listFilesByPrefix().catch(console.error);

PHP

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

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

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:

use Google\Cloud\Storage\StorageClient;

/**
 * List Cloud Storage bucket objects.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function list_objects(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    foreach ($bucket->objects() as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

use Google\Cloud\Storage\StorageClient;

/**
 * List Cloud Storage bucket objects with specified prefix.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $directoryPrefix the prefix to use in the list objects API call.
 *        (e.g. 'myDirectory/')
 */
function list_objects_with_prefix(string $bucketName, string $directoryPrefix): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $options = ['prefix' => $directoryPrefix];
    foreach ($bucket->objects($options) as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

Python

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

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

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:

from google.cloud import storage


def list_blobs(bucket_name):
    """Lists all the blobs in the bucket."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    # Note: Client.list_blobs requires at least package version 1.17.0.
    blobs = storage_client.list_blobs(bucket_name)

    # Note: The call returns a response only when the iterator is consumed.
    for blob in blobs:
        print(blob.name)

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

from google.cloud import storage


def list_blobs_with_prefix(bucket_name, prefix, delimiter=None):
    """Lists all the blobs in the bucket that begin with the prefix.

    This can be used to list all blobs in a "folder", e.g. "public/".

    The delimiter argument can be used to restrict the results to only the
    "files" in the given "folder". Without the delimiter, the entire tree under
    the prefix is returned. For example, given these blobs:

        a/1.txt
        a/b/2.txt

    If you specify prefix ='a/', without a delimiter, you'll get back:

        a/1.txt
        a/b/2.txt

    However, if you specify prefix='a/' and delimiter='/', you'll get back
    only the file directly under 'a/':

        a/1.txt

    As part of the response, you'll also get back a blobs.prefixes entity
    that lists the "subfolders" under `a/`:

        a/b/


    Note: If you only want to list prefixes a/b/ and don't want to iterate over
    blobs, you can do

    ```
    for page in blobs.pages:
        print(page.prefixes)
    ```
    """

    storage_client = storage.Client()

    # Note: Client.list_blobs requires at least package version 1.17.0.
    blobs = storage_client.list_blobs(
        bucket_name, prefix=prefix, delimiter=delimiter
    )

    # Note: The call returns a response only when the iterator is consumed.
    print("Blobs:")
    for blob in blobs:
        print(blob.name)

    if delimiter:
        print("Prefixes:")
        for prefix in blobs.prefixes:
            print(prefix)

Ruby

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

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

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:

def list_files bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name

  bucket.files.each do |file|
    puts file.name
  end
end

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

def list_files_with_prefix bucket_name:, prefix:, delimiter: nil
  # Lists all the files in the bucket that begin with the prefix.
  #
  # This can be used to list all files in a "folder", e.g. "public/".
  #
  # The delimiter argument can be used to restrict the results to only the
  # "files" in the given "folder". Without the delimiter, the entire tree under
  # the prefix is returned. For example, given these files:
  #
  #     a/1.txt
  #     a/b/2.txt
  #
  # If you just specify `prefix: "a"`, you will get back:
  #
  #     a/1.txt
  #     a/b/2.txt
  #
  # However, if you specify `prefix: "a"` and `delimiter: "/"`, you will get back:
  #
  #     a/1.txt

  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The directory prefix to search for
  # prefix = "a"

  # The delimiter to be used to restrict the results
  # delimiter = "/"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name
  files   = bucket.files prefix: prefix, delimiter: delimiter

  files.each do |file|
    puts file.name
  end
end

Rust

בדוגמה הבאה מוצגת רשימה של כל האובייקטים בקטגוריה:

use google_cloud_gax::paginator::ItemPaginator;
use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let mut objects = client
        .list_objects()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .by_item();
    println!("listing objects in bucket {bucket_id}");
    while let Some(object) = objects.next().await.transpose()? {
        println!("{object:?}");
    }
    println!("DONE");
    Ok(())
}

בדוגמה הבאה מוצגת רשימה רק של האובייקטים עם הקידומת הנתונה:

use google_cloud_gax::paginator::ItemPaginator;
use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const PREFIX: &str = "prefixes/are-not-always/folders-";
    let mut objects = client
        .list_objects()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .set_prefix(PREFIX)
        .by_item();
    println!("listing objects in bucket {bucket_id} with prefix {PREFIX}");
    while let Some(object) = objects.next().await.transpose()? {
        println!("{object:?}");
    }
    println!("DONE");
    Ok(())
}

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

‫API בפורמט JSON

להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.
משתמשים בפקודה cURL כדי להעביר ל-API בפורמט JSON בקשה לקריאת רשימה של אובייקטים:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"
```
כאשר BUCKET_NAME הוא השם של הקטגוריה שאת רשימת האובייקטים שלה אתם רוצים לראות. לדוגמה, my-bucket.

‫API בפורמט XML

להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.
משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט XML באמצעות בקשה של קטגוריית GET:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?list-type=2"
```
כאשר BUCKET_NAME הוא השם של הקטגוריה שאת רשימת האובייקטים שלה אתם רוצים לראות. לדוגמה, my-bucket.

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

הצגת רשימה של האובייקטים בתיקייה

המסוף

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

כניסה לדף Buckets
ברשימת הקטגוריות, לוחצים על שם הקטגוריה שמכילה את התיקייה.
בכרטיסייה Objects שבדף Bucket details, לוחצים על שם התיקייה שאת התוכן שלה רוצים לראות.

שורת הפקודה

משתמשים בפקודה gcloud storage ls כדי להציג את רשימת האובייקטים בתיקייה:

gcloud storage ls gs://BUCKET_NAME/FOLDER_NAME

כאשר:

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

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

‫API בפורמט JSON

כדי להציג רשימה של האובייקטים בתיקייה, משתמשים בבקשה להצגת רשימה של אובייקטים עם הפרמטרים prefix ו-delimiter. כשמגדירים את הפרמטר prefix, פעולת הרשימה מוגבלת להחזרת אובייקטים ותיקיות רק מתחת לתחילית. כשמגדירים את הפרמטר delimiter, הרשימה prefixes[] בתגובה מתמלאת בשמות של תיקיות מתחת לתחילית שצוינה.

לדוגמה:

כדי להציג רשימה של כל האובייקטים בתיקייה image/ בקטגוריה my-bucket, משתמשים בכתובת ה-URL הבאה: "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/".

הפעולה הזו יכולה להחזיר את האובייקטים my-bucket/image/cat.jpeg ו-my-bucket/image/dog.jpeg.
כדי לכלול אובייקטים בתיקיות משנה בתוך image/, מסירים את הפרמטר delimiter: "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image".

יכול להיות שהפונקציה תחזיר את האובייקטים my-bucket/image/cat.jpeg, my-bucket/image/dog.jpeg ו-my-bucket/image/dog/shiba.jpeg.

כדי להשתמש בתווים כלליים בבקשה להצגת רשימת אובייקטים ולהתאים אובייקטים לפי ביטוי glob, משתמשים בפרמטר matchGlob. לדוגמה, matchGlob=**.jpeg תואם לכל האובייקטים שמסתיימים ב-.jpeg. כשמשתמשים ב-matchGlob, צריך להגדיר את delimiter ל-/.

לדוגמה, כדי להתאים את כל האובייקטים בתיקייה image שמסתיימים ב-.jpeg, משתמשים בכתובת ה-URL הבאה: "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/&matchGlob=**.jpeg"

פרטים נוספים על שימוש בפרמטרים לסינון אובייקטים מופיעים במאמרי העזרה של ה-API בפורמט JSON בנושא רשימת אובייקטים.

תרחיש שימוש

השימוש בפקודה prefix כדי להציג את התוכן של תיקייה יכול להיות שימושי אם יש לכם הרשאה רק להצגת רשימה של אובייקטים בתיקייה, אבל לא בכל הקטגוריה. לדוגמה, נניח שיש לכם את התפקיד "צפייה באובייקט אחסון" (roles/storage.objectViewer) ב-IAM בתיקייה המנוהלת my-bucket/my-managed-folder-a/, אבל לא בתיקייה המנוהלת my-bucket/my-managed-folder-b/. כדי לקבל רק את האובייקטים ב-my-managed-folder-a, אפשר לציין prefix=my-managed-folder-a/.

סינון אובייקטים

כשמציגים רשימה של אובייקטים, אפשר להשתמש בתחיליות או בסיומות בבקשה של הרשימה כדי לסנן אובייקטים לפי שם. כדי להשתמש בתווים כלליים ולסנן אובייקטים לפי ביטוי glob, משתמשים בפרמטר matchGlob (או match_glob, בהתאם לספריית הלקוח).

המסוף

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

שורת הפקודה

אפשר להשתמש בתווים כלליים לחיפוש בפקודה gcloud storage ls כדי לסנן אובייקטים לפי קידומת או סיומת. לדוגמה, הפקודה הבאה מציגה רק אובייקטים בקטגוריה my-bucket שהשם שלהם מתחיל ב-image ומסתיים ב-.png:

gcloud storage ls gs://my-bucket/image*.png

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

gs://my-bucket/image.png
gs://my-bucket/image-dog.png
gs://my-bucket/image-cat.png
...

אפשר להשתמש בתווים כלליים לחיפוש עם כוכבית כפולה כדי להתאים לאפס רמות של תיקיות או יותר בנתיב. לדוגמה, הפקודה הבאה מציגה רק אובייקטים שהשם שלהם מסתיים ב-.jpeg בכל תיקייה או תיקיית משנה בקטגוריה my-bucket:

gcloud storage ls gs://my-bucket/**/*.jpeg

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

gs://my-bucket/puppy.jpeg
gs://my-bucket/pug.jpeg
gs://my-bucket/pets/dog.jpeg
...

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

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

סינון אובייקטים לפי הקשרים

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

שורת הפקודה

משתמשים בפקודה gcloud storage objects list:

gcloud storage objects list gs://BUCKET_NAME --metadata-filter='contexts."KEY"="VALUE"'

כאשר:

‫BUCKET_NAME הוא שם הקטגוריה שמכילה את האובייקט שרוצים לסנן לפי הקשר. לדוגמה, my-bucket.
‫KEY הוא מפתח ההקשר שמצורף לאובייקט.
‫VALUE הוא הערך שמשויך למפתח ההקשר.

אם הפעולה בוצעה ללא שגיאות, התגובה תיראה דומה לדוגמה הבאה:

---
bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt
...

הפקודה הבאה מציגה רשימה של אובייקטים עם מפתח ההקשר שצוין, בלי קשר לערך שלו:

gcloud storage objects list gs://BUCKET_NAME --metadata-filter='contexts."KEY":*'

כדי להגביל את הפלט כך שיוצגו רק מפתחות וערכים של הקשר, משתמשים ב---format=contextsonly:

gcloud storage objects list gs://BUCKET_NAME --metadata-filter='contexts."KEY":*' --format=contextsonly

אם הפעולה בוצעה ללא שגיאות, התגובה תיראה דומה לדוגמה הבאה:

---
Department: HR
DataClassification: Confidential

ספריות לקוח

Java

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

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


import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ListObjectContexts {
  public static void listObjectContexts(String projectId, String bucketName, String key)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The context key you want to filter
    // String key = "your-context-key";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      /*
       * List any object that has a context with the specified key attached
       * String filter = "contexts.\"KEY\":*";
       *
       * List any object that that does not have a context with the specified key attached
       * String filter = "NOT contexts.\"KEY\":*";
       *
       * List any object that has a context with the specified key and value attached
       * String filter = "contexts.\"KEY\"=\"VALUE\"";
       *
       * List any object that does not have a context with the specified key and value attached
       * String filter = "NOT contexts.\"KEY\"=\"VALUE\"";
       */

      String filter = "contexts.\"" + key + "\":*";

      System.out.println("Listing objects for bucket: " + bucketName + "with context key: " + key);
      Page<Blob> blobs = storage.list(bucketName, Storage.BlobListOption.filter(filter));
      for (Blob blob : blobs.iterateAll()) {
        System.out.println(blob.getBlobId().toGsUtilUri());
      }
    }
  }
}

Rust

use google_cloud_gax::paginator::ItemPaginator;
use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let mut objects = client
        .list_objects()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .set_filter("contexts.\"example\":*")
        .by_item();
    println!("listing objects in bucket {bucket_id} with an context named `example`");
    while let Some(object) = objects.next().await.transpose()? {
        println!("{object:?}");
    }
    println!("done");
    Ok(())
}

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

‫API בפורמט JSON

בדוגמה של בקשת Object: list אפשר לראות איך משתמשים בפרמטרים של שאילתה filter כדי לסנן אובייקטים לפי הקשר.

בדוגמה הבאה, הסינון מתבצע לפי צמד מפתח/ערך:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/?filter=contexts.%22KEY%22%3D%22VALUE%22"

כאשר:

‫BUCKET_NAME הוא שם הקטגוריה שמכילה את האובייקט שרוצים לסנן לפי ההקשר שלו. לדוגמה, my-bucket.
‫KEY הוא מפתח ההקשר שמצורף לאובייקט.
‫VALUE הוא הערך שמשויך למפתח ההקשר.

תחביר

‫Cloud Storage תומך בתחביר הבא של המסנן.

תחביר	תיאור
`contexts."KEY":*`	התאמה לכל אובייקט שיש לו הקשר עם המפתח שצוין.
`contexts."KEY"="VALUE"`	התאמה לכל אובייקט שיש לו הקשר עם המפתח והערך שצוינו.
`NOT contexts."KEY":` או `-contexts."KEY":`	התאמה לכל אובייקט שאין לו הקשר עם המפתח שצוין.
`NOT contexts."KEY"="VALUE"` או `-contexts."KEY"="VALUE"`	התאמה לכל אובייקט שלא מצורף אליו הקשר עם המפתח והערך שצוינו.

שיקולי ביצועים כשיוצרים רשימות אובייקטים

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

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

לפני שמתחילים

ההרשאות הנדרשות

הצגת רשימה של האובייקטים בקטגוריה

המסוף

שורת הפקודה

ספריות לקוח

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

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

‫API בפורמט JSON

‫API בפורמט XML

הצגת רשימה של האובייקטים בתיקייה

המסוף

שורת הפקודה

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

‫API בפורמט JSON

תרחיש שימוש

סינון אובייקטים

המסוף

שורת הפקודה

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

סינון אובייקטים לפי הקשרים

שורת הפקודה

ספריות לקוח

Java

Rust

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

‫API בפורמט JSON

תחביר

שיקולי ביצועים כשיוצרים רשימות אובייקטים

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

הצגת רשימה של אובייקטים