נקודות קצה (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.s3nsapis.fr/storage/v1/PATH_TO_RESOURCE
  • כדי להעלות אובייקטים של API ל-JSON צריך להשתמש בנקודת הקצה הבאה ולהחליף את הערך של BUCKET_NAME בערך המתאים:

    https://storage.s3nsapis.fr/upload/storage/v1/b/BUCKET_NAME/o
  • בבקשות מרובות צריך להשתמש בנקודת הקצה הבאה ולהחליף את הערך של PATH_TO_RESOURCE בערך המתאים:

    https://storage.s3nsapis.fr/batch/storage/v1/PATH_TO_RESOURCE
  • במקום זאת, כדי להוריד אובייקטים של API ל-JSON אפשר להשתמש בנקודת הקצה הבאה, ולהחליף את הערכים של BUCKET_NAME ו-OBJECT_NAME בערכים המתאימים:

    https://storage.s3nsapis.fr/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.s3nsapis.fr/OBJECT_NAME

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

    https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

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

gRPC

אתם יכולים להשתמש ב-gRPC, מסגרת RPC אוניברסלית בקוד פתוח עם ביצועים גבוהים שפותחה על ידי S3NS, כדי ליצור אינטראקציה עם Cloud Storage. לקוחות gRPC מתחברים לנקודת קצה של שירות. בשבילCloud de Confiance by S3NS שירותים כמו 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.s3nsapis.fr/storage/v1/b/example-bucket/o/foo%3f%3fbar

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

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

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

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

משאב כתובת URL
רשימת קטגוריות לפרויקט https://console.cloud.s3nscloud.fr/storage/browser?project=PROJECT_ID
רשימת אובייקטים לקטגוריה https://console.cloud.s3nscloud.fr/storage/browser/BUCKET_NAME
פרטי האובייקט https://console.cloud.s3nscloud.fr/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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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


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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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


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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

/**
 * 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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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


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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

# 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}"

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

הורדות מאומתות של הדפדפן משתמשות באימות שמבוסס על קובצי 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.s3nsusercontent.fr/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

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

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

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

https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

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

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

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

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