List Objects

本頁面說明如何列出儲存在 Cloud Storage bucket 中的物件。物件會依名稱的字母順序排列。

事前準備

如要取得列出物件所需的權限，請要求管理員針對包含要列出物件的 bucket，授予您 Storage 物件檢視者 (roles/storage.objectViewer) IAM 角色。如要列出代管資料夾中的物件，可以對包含要查看物件的代管資料夾授予 roles/storage.objectViewer，而非對值區授予。

如果您打算使用 Google Cloud 控制台執行本頁的工作，請要求管理員授予您「檢視者」(roles/viewer) 基本角色和「Storage 物件檢視者」(roles/storage.objectViewer) 角色。

這些角色具備列出物件所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

• storage.objects.list
• storage.buckets.list
  • 只有在您想使用 Google Cloud 控制台執行本頁工作時，才需要這項權限。

您也可以透過其他預先定義的角色或自訂角色取得這些權限。

如要瞭解如何授予 bucket 角色，請參閱「設定及管理 bucket 的 IAM 政策」。

列出值區中的物件

控制台

1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
   

   前往「Buckets」(值區) 頁面

2. 在 bucket 清單中，按一下要查看內容的 bucket 名稱。

指令列

使用 gcloud storage ls 指令：

gcloud storage ls gs://BUCKET_NAME

其中：

• BUCKET_NAME 是 bucket 的名稱，其中包含您要列出的物件。例如：my-bucket。

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

/**
 * 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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會列出值區中所有的物件：

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(())
}

REST API

JSON API

1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

2. 使用 cURL 呼叫 JSON API，並要求列出物件：

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

   其中 BUCKET_NAME 是要列出物件的 bucket 名稱。例如：my-bucket。

XML API

1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

2. 使用 cURL 透過 GET 值區要求來呼叫 XML API：

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

   其中 BUCKET_NAME 是要列出物件的 bucket 名稱。例如：my-bucket。

   您可以使用 prefix=PREFIX 查詢字串參數，將結果限制為具有指定前置字串的物件。

列出資料夾中的物件

控制台

1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
   

   前往「Buckets」(值區) 頁面

2. 在 bucket 清單中，按一下含有資料夾的 bucket 名稱。

3. 在「Bucket details」(值區詳細資料) 頁面的「Objects」(物件) 分頁中，按一下要查看內容的資料夾名稱。

指令列

使用 gcloud storage ls 指令列出資料夾中的物件：

gcloud storage ls gs://BUCKET_NAME/FOLDER_NAME

其中：

• BUCKET_NAME 是資料夾所在的 bucket 名稱。例如：my-bucket。

• FOLDER_NAME 是要列出物件的資料夾名稱。例如：my-folder。

REST API

JSON API

如要列出資料夾中的物件，請使用列出物件要求，並搭配 prefix 和 delimiter 參數。設定 prefix 參數後，清單作業的範圍會限定為只傳回前置字元下的物件和資料夾。設定 delimiter 參數後，回應中的 prefixes[] 清單會填入指定前置字串下的資料夾名稱。

例如：

• 如要列出 bucket my-bucket 中資料夾 image/ 內的所有物件，請使用下列網址："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 的物件，請使用下列網址： "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/&matchGlob=**.jpeg"

如要進一步瞭解如何使用參數篩選物件，請參閱物件清單 JSON API 參考文件。

用途

如果您只有列出資料夾中物件的權限，但沒有列出整個 bucket 的權限，可以使用 prefix 列出資料夾內容。舉例來說，假設您擁有代管資料夾 my-bucket/my-managed-folder-a/ 的 Storage 物件檢視者 (roles/storage.objectViewer) IAM 角色，但沒有代管資料夾 my-bucket/my-managed-folder-b/ 的角色。如要僅傳回 my-managed-folder-a 中的物件，可以指定 prefix=my-managed-folder-a/。

注意： 依代管資料夾篩選時，請將 includeFoldersAsPrefixes 參數設為 true，並將 delimiter 參數設為 /。

篩選物件

列出物件時，您可以在清單要求中使用前置字串或後置字串，依名稱篩選物件。如要使用萬用字元，並依 glob 運算式篩選物件，請使用 matchGlob 參數 (或 match_glob，視用戶端程式庫而定)。

控制台

如要瞭解如何篩選及排序 bucket 或資料夾中的物件，請參閱「篩選及排序」。

指令列

您可以在 gcloud storage ls 指令中使用萬用字元，依前置字元或後置字元篩選物件。舉例來說，下列指令只會列出 bucket 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 的物件，這些物件位於 bucket 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
...

REST API

如要瞭解如何依資料夾或物件名稱前置字串篩選物件，請參閱「列出資料夾中的物件」。

依結構定義篩選物件

列出物件時，您可以使用篩選器，只顯示符合指定情境的物件。

指令列

使用 gcloud storage objects list 指令：

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

其中：

• BUCKET_NAME 是 bucket 的名稱，其中包含要依情境篩選的物件。例如：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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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(())
}

REST API

JSON API

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 是 bucket 的名稱，其中包含您要依據其背景資訊篩選的物件。例如：my-bucket。
• KEY 是附加至物件的內容索引鍵。
• VALUE 是與情境索引鍵相關聯的值。

語法

Cloud Storage 支援下列篩選器語法。

語法	說明
contexts."KEY":*	比對任何具有附加指定鍵的結構定義物件。
contexts."KEY"="VALUE"	比對任何具有脈絡資料且附加指定鍵和值的物件。
NOT contexts."KEY":* OR -contexts."KEY":*	比對任何未附加指定索引鍵內容的物件。
NOT contexts."KEY"="VALUE" OR -contexts."KEY"="VALUE"	比對任何不含指定鍵和值的物件。

列出物件時的效能考量

與平面命名空間 bucket 相比，啟用階層命名空間的 bucket 底層結構會影響列出物件作業的效能。詳情請參閱「在已啟用階層命名空間的 bucket 中提高效能」。

後續步驟

• 從您的值區下載物件。
• 查看及編輯物件中繼資料。
• 從值區刪除物件。
• 瞭解如何將結果分頁。