יצירת קטגוריה

בדף הזה מוסבר איך ליצור קטגוריה ב-Cloud Storage. אם לא צוין אחרת בבקשה, קטגוריות נוצרות עם סוג האחסון (storage class) Standard Storage שמוגדר כברירת מחדל, ועם משך שמירה של 7 ימים של מחיקה רכה.

אם אתם יוצרים קטגוריה בפעם הראשונה, כדאי לעיין במאמר אחסון אובייקטים באמצעות מסוף Cloud de Confiance או במאמר אחסון אובייקטים באמצעות Google Cloud CLI כדי לקבל הסבר מפורט יותר על המשימות שאפשר לבצע באמצעות Cloud Storage.

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

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

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

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

  • storage.buckets.create
  • storage.buckets.enableObjectRetention (נדרש רק אם מפעילים הגדרות שמירה של אובייקטים בקטגוריה)
  • storage.buckets.list (נדרשת רק אם יוצרים קטגוריה באמצעות מסוף Cloud de Confiance ).
  • resourcemanager.projects.get (נדרשת רק אם יוצרים קטגוריה באמצעות מסוף Cloud de Confiance )

יכול להיות שתוכלו לקבל את ההרשאות האלה גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים. במאמר תפקידי IAM ל-Cloud Storage מפורטים התפקידים השונים וההרשאות שמשויכות אליהם.

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

יצירת קטגוריה חדשה

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

המסוף

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

    כניסה לדף Buckets

  2. לוחצים על יצירה.
  3. ממלאים את פרטי הקטגוריה בדף Create a bucket. אחרי כל אחד מהשלבים הבאים, לוחצים על המשך כדי לעבור לשלב הבא:

    1. בקטע Get started (תחילת העבודה), מבצעים את הפעולות הבאות:

      • מזינים שם ייחודי בהיקף גלובלי שעומד בקריטריונים לשמות של קטגוריות.

      • כדי להוסיף תווית של דלי, לוחצים על חץ ההרחבה כדי להרחיב את הקטע Labels (תוויות), לוחצים על Add label (הוספת תווית) ומציינים key ו-value בשביל התווית.

    2. בקטע Choose where to store your data, מבצעים את הפעולות הבאות:

      1. בוחרים סוג מיקום.

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

    3. בקטע Choose how to store your data מבצעים את הפעולות הבאות:

      1. בוחרים default storage class לקטגוריה או Autoclass לניהול אוטומטי של סוג האחסון (storage class) של נתוני הקטגוריה.

      2. בקטע Optimize storage for data-intensive workloads: מבצעים את הפעולות הבאות:

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

        • כדי להפעיל את Rapid Cache, בוחרים באפשרות Enable Rapid Cache ופועלים לפי השלבים:
          1. כדי ליצור מטמונים, לוחצים על Configure (הגדרה).

          2. בתיבת הדו-שיח הגדרת הגדרות מטמון שמופיעה, לוחצים על החץ לתפריט הנפתח לצד האזורים שמופיעים ברשימה ובוחרים את האזורים שבהם רוצים ליצור מטמונים.

          3. לוחצים על סיום.

    4. בקטע Choose how to control access to objects, בוחרים אם הקטגוריה אוכפת public access prevention או לא, ואז בוחרים גישה אחידה ברמת הקטגוריה לאובייקטים של הקטגוריה.

    5. בקטע Choose how to protect object data:

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

      • כדי לשנות את משך הזמן שבו מחיקה רכה שומרת אובייקטים אחרי המחיקה, מסמנים את התיבה Soft delete policy (מדיניות מחיקה רכה) ואז בוחרים באפשרות Set custom retention duration (הגדרת משך שמירה מותאם אישית). לאחר מכן, מציינים כמה זמן רוצים לשמור את האובייקטים שנמחקו.

        כדי להשבית את המחיקה הרכה, למשל אם המאגר יכיל בעיקר נתונים זמניים לזמן קצר, מבטלים את הסימון בתיבת הסימון Soft delete policy (מדיניות מחיקה רכה).

      • כדי לבחור איך להצפין את נתוני האובייקט, לוחצים על החץ להרחבה עם התווית Data encryption (הצפנת נתונים) ופועלים לפי השלבים הבאים:

  4. לוחצים על יצירה.

במאמר פתרון בעיות מוסבר איך מקבלים מידע מפורט על שגיאות בנושא פעולות ב-Cloud Storage שנכשלו ב Cloud de Confiance מסוף.

שורת הפקודה

  1. במסוף Cloud de Confiance , מפעילים את Cloud Shell.

    הפעלת Cloud Shell

    בחלק התחתון של Cloud de Confiance המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

  2. בסביבת הפיתוח, מריצים את הפקודה gcloud storage buckets create:

    gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION

    כאשר:

    • BUCKET_NAME הוא השם שרוצים לתת לקטגוריה, בכפוף לדרישות למתן שמות. לדוגמה: my-bucket.
    • BUCKET_LOCATION הוא המיקום של הקטגוריה. לדוגמה, U-FRANCE-EAST1.

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

    Creating gs://BUCKET_NAME/...

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

    • --project: ציון מזהה הפרויקט או מספר הפרויקט שאליהם הקטגוריה תשויך. לדוגמה, my-project.
    • --default-storage-class: ציון סוג האחסון של הקטגוריה שמוגדר כברירת מחדל. לדוגמה, STANDARD.
    • --uniform-bucket-level-access: הפעלת גישה אחידה ברמת הקטגוריה בשביל הקטגוריה.
    • --soft-delete-duration: מציינים את משך השמירה של מחיקה רכה, כלומר מספר הימים שבהם רוצים לשמור אובייקטים אחרי שהם נמחקים. לדוגמה, 10d.
    • --encryption-enforcement-file: מספקים קובץ שמגדיר אילו שיטות הצפנה מוגבלות או מותרות לאובייקטים חדשים בקטגוריה.

    לדוגמה:

    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_ID --default-storage-class=STORAGE_CLASS --location=BUCKET_LOCATION --uniform-bucket-level-access
    --soft-delete-duration=RETENTION_DURATION --encryption-enforcement-file=ENCRYPTION_ENFORCEMENT_FILE
    

    רשימה מלאה של האפשרויות ליצירת קטגוריות באמצעות ה-CLI של gcloud מופיעה במאמר אפשרויות של buckets create.

ספריות לקוח

C++

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& storage_class, std::string const& location) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.CreateBucket(bucket_name, gcs::BucketMetadata()
                                           .set_storage_class(storage_class)
                                           .set_location(location));
  if (!bucket_metadata) throw std::move(bucket_metadata).status();

  std::cout << "Bucket " << bucket_metadata->name() << " created."
            << "\nFull Metadata: " << *bucket_metadata << "\n";
}

C#

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class CreateRegionalBucketSample
{
    /// <summary>
    /// Creates a storage bucket with region.
    /// </summary>
    /// <param name="projectId">The ID of the project to create the buckets in.</param>
    /// <param name="location">The location of the bucket. Object data for objects in the bucket resides in 
    /// physical storage within this region. Defaults to US.</param>
    /// <param name="bucketName">The name of the bucket to create.</param>
    /// <param name="storageClass">The bucket's default storage class, used whenever no storageClass is specified
    /// for a newly-created object. This defines how objects in the bucket are stored
    /// and determines the SLA and the cost of storage. Values include MULTI_REGIONAL,
    /// REGIONAL, STANDARD, NEARLINE, COLDLINE, ARCHIVE, and DURABLE_REDUCED_AVAILABILITY.
    /// If this value is not specified when the bucket is created, it will default to
    /// STANDARD.</param>
    public Bucket CreateRegionalBucket(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name",
        string location = "us-west1",
        string storageClass = "REGIONAL")
    {
        var storage = StorageClient.Create();
        Bucket bucket = new Bucket
        {
            Location = location,
            Name = bucketName,
            StorageClass = storageClass
        };
        var newlyCreatedBucket = storage.CreateBucket(projectId, bucket);
        Console.WriteLine($"Created {bucketName}.");
        return newlyCreatedBucket;
    }
}

Go

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

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

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

// createBucketClassLocation creates a new bucket in the project with Storage class and
// location.
func createBucketClassLocation(w io.Writer, projectID, bucketName string) error {
	// projectID := "my-project-id"
	// bucketName := "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*30)
	defer cancel()

	storageClassAndLocation := &storage.BucketAttrs{
		StorageClass: "COLDLINE",
		Location:     "asia",
	}
	bucket := client.Bucket(bucketName)
	if err := bucket.Create(ctx, projectID, storageClassAndLocation); err != nil {
		return fmt.Errorf("Bucket(%q).Create: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Created bucket %v in %v with storage class %v\n", bucketName, storageClassAndLocation.Location, storageClassAndLocation.StorageClass)
	return nil
}

Java

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageClass;
import com.google.cloud.storage.StorageOptions;

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

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

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    // See the StorageClass documentation for other valid storage classes:
    // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
    StorageClass storageClass = StorageClass.COLDLINE;

    // See this documentation for other valid locations:
    // http://g.co/cloud/storage/docs/bucket-locations#location-mr
    String location = "ASIA";

    Bucket bucket =
        storage.create(
            BucketInfo.newBuilder(bucketName)
                .setStorageClass(storageClass)
                .setLocation(location)
                .build());

    System.out.println(
        "Created bucket "
            + bucket.getName()
            + " in "
            + bucket.getLocation()
            + " with storage class "
            + bucket.getStorageClass());
  }
}

Node.js

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

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

// The name of a storage class
// See the StorageClass documentation for other valid storage classes:
// https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
// const storageClass = 'coldline';

// The name of a location
// See this documentation for other valid locations:
// http://g.co/cloud/storage/docs/locations#location-mr
// const location = 'ASIA';

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

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createBucketWithStorageClassAndLocation() {
  // For default values see: https://cloud.google.com/storage/docs/locations and
  // https://cloud.google.com/storage/docs/storage-classes
  const [bucket] = await storage.createBucket(bucketName, {
    location,
    [storageClass]: true,
  });

  console.log(
    `${bucket.name} created with ${storageClass} class in ${location}`
  );
}

createBucketWithStorageClassAndLocation().catch(console.error);

PHP

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

use Google\Cloud\Storage\StorageClient;

/**
 * Create a new bucket with a custom default storage class and location.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function create_bucket_class_location(string $bucketName): void
{
    $storage = new StorageClient();
    $storageClass = 'COLDLINE';
    $location = 'ASIA';
    $bucket = $storage->createBucket($bucketName, [
        'storageClass' => $storageClass,
        'location' => $location,
    ]);

    $objects = $bucket->objects([
        'encryption' => [
            'defaultKmsKeyName' => null,
        ]
    ]);

    printf('Created bucket %s in %s with storage class %s', $bucketName, $storageClass, $location);
}

Python

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

from google.cloud import storage


def create_bucket_class_location(bucket_name):
    """
    Create a new bucket in the US region with the coldline storage
    class
    """
    # bucket_name = "your-new-bucket-name"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)
    bucket.storage_class = "COLDLINE"
    new_bucket = storage_client.create_bucket(bucket, location="us")

    print(
        "Created bucket {} in {} with storage class {}".format(
            new_bucket.name, new_bucket.location, new_bucket.storage_class
        )
    )
    return new_bucket

Ruby

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

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

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

def create_bucket_class_location bucket_name:
  # The ID to give your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.create_bucket bucket_name,
                                  location:      "ASIA",
                                  storage_class: "COLDLINE"

  puts "Created bucket #{bucket.name} in #{bucket.location} with #{bucket.storage_class} class"
end

Rust

use google_cloud_storage::{client::StorageControl, model::Bucket};

pub async fn sample(
    client: &StorageControl,
    project_id: &str,
    bucket_id: &str,
) -> anyhow::Result<()> {
    let bucket = client
        .create_bucket()
        .set_parent("projects/_")
        .set_bucket_id(bucket_id)
        .set_bucket(
            Bucket::new()
                .set_project(format!("projects/{project_id}"))
                .set_storage_class("NEARLINE")
                .set_location("US-CENTRAL1"),
        )
        .send()
        .await?;
    println!("successfully created bucket {bucket:?}");
    Ok(())
}

Terraform

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

# Create new storage bucket in the US multi-region
# with coldline storage
resource "random_id" "bucket_prefix" {
  byte_length = 8
}

resource "google_storage_bucket" "static" {
  name          = "${random_id.bucket_prefix.hex}-new-bucket"
  location      = "US"
  storage_class = "COLDLINE"

  uniform_bucket_level_access = true
}

ממשקי API ל-REST

‫API בפורמט JSON

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

  2. יוצרים קובץ JSON עם ההגדרות של הקטגוריה, שחייבות לכלול name לקטגוריה. רשימה מלאה של ההגדרות מופיעה במאמרי העזרה של Buckets:Insert. ההגדרות הנפוצות שצריך לכלול בקובץ:

    {
      "name": "BUCKET_NAME",
      "location": "BUCKET_LOCATION",
      "storageClass": "STORAGE_CLASS",
      "iamConfiguration": {
        "uniformBucketLevelAccess": {
          "enabled": true
        },
      }
    }

    כאשר:

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

    • BUCKET_LOCATION הוא המיקום שבו רוצים לאחסן את נתוני האובייקטים של הקטגוריה. לדוגמה, U-FRANCE-EAST1.

    • STORAGE_CLASS הוא סוג האחסון שמוגדר כברירת מחדל בקטגוריה. לדוגמה, STANDARD.

  3. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON:

    curl -X POST --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.s3nsapis.fr/storage/v1/b?project=PROJECT_IDENTIFIER"

    כאשר:

    • JSON_FILE_NAME הוא השם של קובץ ה-JSON שיצרתם בשלב 2.
    • PROJECT_IDENTIFIER הוא המזהה או המספר של הפרויקט שאליו הקטגוריה תשויך. לדוגמה, my-project.

‫API בפורמט XML

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

  2. יוצרים קובץ XML עם ההגדרות של הקטגוריה. רשימה מלאה של ההגדרות מופיעה במאמרי העזרה בנושא XML: Create a bucket. אלו ההגדרות הנפוצות שצריך לכלול:

    <CreateBucketConfiguration>
      <StorageClass>STORAGE_CLASS</StorageClass>
      <LocationConstraint>BUCKET_LOCATION</LocationConstraint>
    </CreateBucketConfiguration>

    כאשר:

    • STORAGE_CLASS הוא סוג האחסון שמוגדר כברירת מחדל בקטגוריה. לדוגמה, STANDARD.

    • BUCKET_LOCATION הוא המיקום שבו רוצים לאחסן את נתוני האובייקטים של הקטגוריה. לדוגמה, U-FRANCE-EAST1.

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

    curl -X PUT --data-binary @XML_FILE_NAME \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "x-goog-project-id: PROJECT_ID" \
      "https://storage.s3nsapis.fr/BUCKET_NAME"

    כאשר:

    • XML_FILE_NAME הוא השם של קובץ ה-XML שיצרתם בשלב 2.
    • PROJECT_ID הוא מזהה הפרויקט שאליו הקטגוריה תשויך. לדוגמה, my-project.
    • BUCKET_NAME הוא השם שרוצים לתת לקטגוריה, בכפוף לדרישות למתן שמות. לדוגמה: my-bucket.

    כשהבקשה מסתיימת בהצלחה, לא מוחזרת תגובה.

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