נקודות קצה (endpoints) של בקשות

בדף הזה נסביר באילו נקודות קצה (endpoints) אפשר להשתמש בבקשות כדי לגשת ל-Cloud Storage. השירות Cloud Storage תומך בפרוטוקולים HTTP/1.1,‏ HTTP/2 ו-HTTP/3. נקודת קצה היא המיקום שבו אפשר לגשת ל-Cloud Storage, והיא מופיעה ככתובת URL.

בקשות API אופייניות

API ל-JSON

כששולחים בקשות API בפורמט JSON ישירות ל-Cloud Storage, צריך להשתמש בנקודות הקצה הבאות:

  • בבקשות כלליות של API ל-JSON, לא כולל העלאות של אובייקטים, צריך להשתמש בנקודת הקצה הבאה ולהחליף את הערך של PATH_TO_RESOURCE בערך המתאים:

    https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE

  • כדי להעלות אובייקטים של API ל-JSON צריך להשתמש בנקודת הקצה הבאה ולהחליף את הערך של BUCKET_NAME בערך המתאים:

    https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

  • בבקשות מרובות צריך להשתמש בנקודת הקצה הבאה ולהחליף את הערך של PATH_TO_RESOURCE בערך המתאים:

    https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE

  • במקום זאת, כדי להוריד אובייקטים של API ל-JSON אפשר להשתמש בנקודת הקצה הבאה, ולהחליף את הערכים של BUCKET_NAME ו-OBJECT_NAME בערכים המתאימים:

    https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

נקודות הקצה של API ל-JSON מקבלות רק בקשות HTTPS.

‫API בפורמט XML

כששולחים בקשות API בפורמט XML ישירות ל-Cloud Storage, צריך להשתמש בנקודת הקצה בפורמט של מארח וירטואלי או בפורמט של נתיב, ולהחליף את הערכים של BUCKET_NAME ו-OBJECT_NAME בערכים המתאימים:

  • נקודת קצה בפורמט של מארח וירטואלי: 

    https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME

  • נקודת קצה בפורמט של נתיב: 

    https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

נקודות הקצה ב-API ל-XML תומכות בשכבת שקע מאובטחת (פרוטוקול SSL) ולכן אפשר להשתמש ב-HTTP או ב-HTTPS. מומלץ להשתמש ב-HTTPS, במיוחד אם אתם משתמשים ב-OAuth 2.0 כדי לאמת ב-Cloud Storage.

gRPC

אתם יכולים להשתמש ב-gRPC, מסגרת RPC אוניברסלית בקוד פתוח עם ביצועים גבוהים שפותחה על ידי Google, כדי ליצור אינטראקציה עם Cloud Storage. לקוחות gRPC מתחברים לנקודת קצה של שירות. בשבילGoogle Cloud שירותים כמו Cloud Storage, זו בדרך כלל כתובת DNS בדומיין googleapis.com (לדוגמה, storage.googleapis.com) והיא משתמשת ביציאות מאובטחות רגילות כמו 443. שימוש ב-gRPC יכול לשפר את הביצועים ולספק יכולות סטרימינג יעילות.

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

מפעילים את gRPC בספריית לקוח באמצעות אחת מהשפות הנתמכות הבאות:

למידע על שיטות מומלצות לחיבור דרך שרת proxy, ראו פתרון בעיות.

קידוד של חלקים בנתיב כתובת ה-URL

בנוסף לשיקולים הכלליים לגבי בחירת שמות לקטגוריות ובחירת שמות לאובייקטים, כדי להבטיח תאימות בכל הכלים של Cloud Storage, כשמופיעים בכתובת ה-URL של הבקשה התווים הבאים בשם האובייקט או במחרוזת השאילתה, אתם צריכים לקודד אותם:

‫!,‏ #,‏ $,‏ &,‏ ',‏ (,‏ ),‏ *,‏ +,‏ ,,‏ /,‏ :,‏ ;,‏ =,‏ ?,‏ @,‏ [,‏ ] ותווי רווח.

לדוגמה, אם שולחים בקשת GET ל-API ל-JSON בשביל אובייקט בשם foo??bar בקטגוריה example-bucket, כתובת ה-URL של הבקשה צריכה להיות:

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

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

מידע נוסף על שימוש בקידוד עם אחוזים מופיע ב-Section 3.3 Path ב-RFC 3986.

Google Cloud נקודות קצה במסוף

כשעובדים במסוף Google Cloud , ניגשים למשאבים שונים באמצעות כתובות ה-URL הבאות:

משאב כתובת URL
רשימת קטגוריות לפרויקט https://console.cloud.google.com/storage/browser?project=PROJECT_ID
רשימת אובייקטים לקטגוריה https://console.cloud.google.com/storage/browser/BUCKET_NAME
פרטי האובייקט https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
נתוני האובייקט מידע על הורדות מאומתות בדפדפן

נקודות קצה ב-gcloud

‫פקודות gcloud storage משתמשות בנקודות קצה של API ל-JSON. השימוש בנקודת הקצה מנוהל בשמכם על ידי ה-CLI של gcloud.

נקודות קצה של ספריות לקוח

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

C++

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

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

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
      "https://storage.googleapis.com"));
  PerformSomeOperations(client, bucket_name, object_name);
}

C#

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

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


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

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w io.Writer, customEndpoint string, opts ...option.ClientOption) error {
	// customEndpoint := "https://my-custom-endpoint.example.com/storage/v1/"
	// opts := []option.ClientOption{}
	ctx := context.Background()

	// Add the custom endpoint option to any other desired options passed to storage.NewClient.
	opts = append(opts, option.WithEndpoint(customEndpoint))
	client, err := storage.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Use the client as per your custom endpoint, for example, attempt to get a bucket's metadata.
	client.Bucket("bucket-name").Attrs(ctx)
	return nil
}

Java

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

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


import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetClientEndpoint {

  public static void setClientEndpoint(String projectId, String endpoint) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The endpoint you wish to target
    // String endpoint = "https://storage.googleapis.com"

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

    System.out.println(
        "Storage Client initialized with endpoint " + storage.getOptions().getHost());
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The custom endpoint to which requests should be made
// const apiEndpoint = 'https://yourcustomendpoint.com';

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

// Creates a client
const storage = new Storage({
  apiEndpoint: apiEndpoint,
  useAuthWithCustomEndpoint: true,
});

console.log(`Client initiated with endpoint: ${storage.apiEndpoint}.`);

PHP

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

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

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a custom endpoint for storage client.
 *
 * @param string $projectId The ID of your Google Cloud Platform project.
 *        (e.g. 'my-project-id')
 * @param string $endpoint The endpoint for storage client to target.
 *        (e.g. 'https://storage.googleapis.com')
 */
function set_client_endpoint(
    string $projectId,
    string $endpoint
): void {
    $storage = new StorageClient([
        'projectId' => $projectId,
        'apiEndpoint' => $endpoint,
    ]);

    // fetching apiEndpoint and baseUri from StorageClient is excluded for brevity
    # ...
    print('Storage Client initialized.' . PHP_EOL);
}

Python

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

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


from google.cloud import storage


def set_client_endpoint(api_endpoint):
    """Initiates client with specified endpoint."""
    # api_endpoint = 'https://storage.googleapis.com'

    storage_client = storage.Client(client_options={'api_endpoint': api_endpoint})

    print(f"client initiated with endpoint: {storage_client._connection.API_BASE_URL}")

    return storage_client

Ruby

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

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

# api_endpoint = "https://storage.googleapis.com"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new(
  endpoint: api_endpoint
)

puts "Client initiated with endpoint #{storage.service.service.root_url}"

דומיינים מותאמים אישית

אם אתם הבעלים של הדומיין שלכם, תוכלו למפות את מזהי ה-URI שלו לשירות אחד או יותר שלGoogle Cloud , כולל קטגוריות של Cloud Storage. לפעמים משתמשים במונח שם מארח שמקשר בין קטגוריות כדי לתאר את נקודת הקצה של הבקשה ב-Cloud Storage. כדי לקשר דומיין מותאם אישית לקטגוריה של Cloud Storage, צריך ליצור ברשומת ה-DNS הפניה אוטומטית מסוג A או מסוג CNAME.

רשומות A

כשמקשרים דומיין מותאם אישית לקטגוריה של Cloud Storage, בדרך כלל צריך להשתמש ברשומת A.

  • רשומות A תומכות בבקשות HTTPS.
  • אפשר להשתמש ברשומות A כדי לשלוח תעבורת נתונים שמגיעה משם מארח יחיד לכמה קטגוריות, וגם לשירותי Google Cloud אחרים.
  • ברשומות A אין הגבלות על שם הקטגוריה.

החיסרון בשימוש ברשומות A הוא שהן דורשות הגדרות נוספות ומשתמשות במשאבים נוספים של Google Cloud . תוכלו למצוא הוראות לשימוש בדומיינים מותאמים אישית עם רשומות A במאמר הגדרת מאזן העומסים ואישור ה-SSL.

רשומות CNAME

אפשר להשתמש ברשומת CNAME כדי לקשר דומיין מותאם אישית לקטגוריה של Cloud Storage, אבל במגבלות הבאות:

  • רשומות CNAME תומכות רק בבקשות HTTP.
  • רשומות CNAME יכולות להפנות את התעבורה משם המארח נתון רק לקטגוריה אחת.
  • ברשומות CNAME חייבת להיות התאמה בין שם המארח לשם הקטגוריה המשויכת, וחייבים לתקף את שם הקטגוריה.
  • אפשר להשתמש ברשומות CNAME רק בתת-דומיינים כמו www.mydomain.com, ולא בדומיינים ברמה העליונה כמו mydomain.com.

כשמשתמשים ברשומות CNAME, החלק של שם המארח ברשומת CNAME חייב להיות מוגדר באופן הבא:

c.storage.googleapis.com.

לדוגמה, נניח שהדומיין שלכם הוא example.com, ואתם רוצים לאפשר ללקוחות גישה למפות לנסיעה. תוכלו ליצור קטגוריה ב-Cloud Storage בשם travel-maps.example.com, ואז ליצור רשומת CNAME ב-DNS שמפנה מחדש בקשות מ-travel-maps.example.com ל-URI של Cloud Storage. כדי לעשות את זה צריך לפרסם ב-DNS את רשומת ה-CNAME הבאה:

NAME                      TYPE     DATA
travel-maps               CNAME    c.storage.googleapis.com.

כך הלקוחות שלכם יוכלו להשתמש בכתובת ה-URL הבאה כדי לגשת למפה של פריז:

http://travel-maps.example.com/paris.jpg

השירות לרישום דומיינים צריך לאפשר לכם לנהל את הדומיין, כולל האפשרות להוסיף רשומת משאבים מסוג CNAME. לדוגמה, אם משתמשים ב-Cloud DNS, אפשר למצוא הוראות להוספת רשומות משאבים בדף הוספה, שינוי ומחיקה של רשומות.

הורדות מאומתות בדפדפן

הורדות מאומתות של הדפדפן משתמשות באימות שמבוסס על קובצי cookie. כשמפעילים אימות כזה, המשתמשים מתבקשים להיכנס לחשבון המשתמש שלהם כדי לאמת את הזהות שלהם. כדי להוריד את האובייקט, לחשבון שמציינים צריכה להיות הרשאה מתאימה. לדוגמה, אם אתם משתמשים בניהול זהויות והרשאות גישה (IAM) כדי לנהל את הגישה לאובייקטים שלכם, לחשבון של המשתמש צריכה להיות ההרשאה storage.objects.viewer, שמוענקת בתפקיד 'צפייה באובייקט אחסון'.

כדי להוריד אובייקט באמצעות אימות שמבוסס על קובצי Cookie צריך להשתמש בכתובת ה-URL הבאה, ולהחליף את הערכים של BUCKET_NAME ו-OBJECT_NAME בערכים המתאימים:

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

לדוגמה, אם שיתפתם את קובץ האימג' london.jpg מהקטגוריה example-maps, כתובת ה-URL תהיה:

https://storage.cloud.google.com/example-maps/london.jpg

אחרי הכניסה תועברו לתוכן המבוקש. כתובת ה-URL של התוכן הזה היא בפורמט https://ALPHANUMERIC_SEQUENCE-apidata.googleusercontent.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

כשמבצעים הורדות מאומתות של הדפדפן צריך להשתמש ב-HTTPS. אם מנסים להשתמש ב-HTTP, תתבצע הפניה אוטומטית ל-HTTPS.

גישה לאובייקטים שגלויים לכולם

כל הבקשות ל-URI של storage.cloud.google.com מחייבות אימות. הדרישה הזו חלה גם אם ל-allUsers יש הרשאת גישה לאובייקט. אם רוצים שהמשתמשים יורידו אובייקטים שנגישים באופן אנונימי בלי לבצע אימות, צריך להשתמש בנקודת הקצה של API ל-XML בפורמט של נתיב:

https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

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

תמיכה ב-TLS הדדי

‫ Mutual TLS (mTLS) הוא פרוטוקול מקובל בתחום לאימות הדדי בין לקוח לשרת. ‫Cloud Storage תומך בנקודות הקצה הבאות של mTLS:

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