Endpoint permintaan

Halaman ini menjelaskan berbagai endpoint permintaan yang dapat Anda gunakan untuk mengakses Cloud Storage. Cloud Storage mendukung protokol HTTP/1.1, HTTP/2, dan HTTP/3. Endpoint adalah lokasi tempat Cloud Storage dapat diakses, ditulis sebagai URL.

Permintaan API biasa

Untuk koneksi melalui proxy, lihat Topik pemecahan masalah untuk praktik yang direkomendasikan.

Mengenkode bagian jalur URL

Selain pertimbangan umum untuk penamaan bucket dan penamaan objek, guna memastikan kompatibilitas di seluruh alat Cloud Storage, Anda harus mengenkode karakter berikut saat muncul dalam nama objek atau string kueri URL permintaan:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ], dan karakter spasi.

Misalnya, jika Anda mengirim permintaan GET JSON API untuk objek bernama foo??bar dalam bucket example-bucket, URL permintaan Anda harus:

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

Perlu diperhatikan bahwa tidak semua karakter yang tercantum harus dienkode dalam setiap skenario. Selain itu, encoding biasanya ditangani untuk Anda oleh library klien, seperti Library Klien Cloud Storage, sehingga Anda dapat meneruskan nama objek mentah saat menggunakan alat tersebut.

Untuk mengetahui informasi selengkapnya tentang penggunaan enkode dengan persen, lihat Bagian 3.3 Path di RFC 3986.

EndpointGoogle Cloud console

Saat menggunakan konsol Google Cloud , Anda mengakses berbagai resource menggunakan URL berikut:

endpoint gcloud

Perintah gcloud storage menggunakan endpoint API JSON. Penggunaan endpoint dikelola untuk Anda oleh gcloud CLI.

Endpoint library klien

Library klien Cloud Storage mengelola endpoint permintaan secara otomatis. Anda juga dapat menetapkan endpoint permintaan secara manual. Hal ini berguna saat Anda ingin menggunakan endpoint tertentu, atau untuk pengujian, seperti saat Anda ingin menggunakan emulator lokal:

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

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

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

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
}

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

/**
 * 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}.`);

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

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

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

Domain kustom

Jika memiliki domain sendiri, Anda dapat memetakan URI-nya ke satu atau beberapa layananGoogle Cloud , termasuk bucket Cloud Storage. Istilah nama host yang terikat bucket terkadang digunakan untuk menjelaskan endpoint permintaan Cloud Storage ini. Untuk menghubungkan domain kustom ke bucket Cloud Storage, buat pengalihan A atau CNAME di data DNS Anda.

Record A

Saat menghubungkan domain kustom ke bucket Cloud Storage, umumnya Anda harus menggunakan record A.

• Record A mendukung permintaan HTTPS.
• Record A dapat digunakan untuk mengirim traffic yang berasal dari satu nama host ke beberapa bucket serta ke layanan Google Cloud lainnya.
• Record A tidak menempatkan batasan apa pun pada nama bucket Anda.

Kelemahan penggunaan record A adalah bahwa record tersebut memerlukan penyiapan dan penggunaan tambahan resource Google Cloud . Lihat Menyiapkan load balancer dan sertifikat SSL untuk mendapatkan panduan tentang cara menggunakan domain kustom dengan record A.

Record CNAME

Saat menghubungkan domain kustom ke bucket Cloud Storage, Anda dapat menggunakan record CNAME, tetapi perlu diketahui bahwa cara ini memiliki batasan tertentu:

• Record CNAME hanya mendukung permintaan HTTP.
• Record CNAME hanya dapat mengarahkan traffic dari nama host tertentu ke satu bucket.
• Record CNAME memerlukan nama host dan nama bucket terkait agar cocok, dan Anda harus memvalidasi nama bucket.
• Record CNAME hanya dapat digunakan untuk subdomain, misalnya www.mydomain.com, bukan domain level teratas seperti mydomain.com.

Saat menggunakan data CNAME, bagian nama host dari data CNAME Anda harus ditetapkan menjadi berikut:

c.storage.googleapis.com.

Misalnya, domain Anda adalah example.com, dan Anda ingin menyediakan peta perjalanan untuk pelanggan. Anda dapat membuat bucket di Cloud Storage yang bernama travel-maps.example.com, lalu membuat record CNAME di DNS yang mengalihkan permintaan dari travel-maps.example.com ke Cloud Storage URI. Untuk melakukannya, publikasikan record CNAME berikut di DNS:

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

Dengan melakukannya, pelanggan dapat menggunakan URL berikut untuk mengakses peta Paris:

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

Layanan pendaftaran domain harus memiliki cara bagi Anda untuk mengelola domain, termasuk menambahkan record resource CNAME. Misalnya, jika Anda menggunakan Cloud DNS, petunjuk cara menambahkan data resource dapat ditemukan di halaman Menambahkan, mengubah, dan menghapus data.

Download browser terautentikasi

Download browser terautentikasi menggunakan autentikasi berbasis cookie. Autentikasi berbasis cookie meminta pengguna untuk login ke akun pengguna mereka guna membangun identitas mereka. Akun yang ditentukan harus memiliki izin yang sesuai untuk mendownload objek. Misalnya, jika Anda menggunakan Identity and Access Management untuk mengontrol akses ke objek Anda, akun pengguna harus memiliki izin storage.objects.viewer, yang diberikan di peran Storage Object Viewer.

Untuk mendownload objek menggunakan autentikasi berbasis cookie, gunakan URL berikut, dengan mengganti BUCKET_NAME dan OBJECT_NAME dengan nilai yang sesuai:

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

Misalnya, jika Anda membagikan image london.jpg dari bucket example-maps, URL-nya adalah:

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

Setelah berhasil login, Anda akan dialihkan ke konten yang diminta. URL untuk konten ini memiliki format https://ALPHANUMERIC_SEQUENCE-apidata.googleusercontent.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

Penggunaan HTTPS diperlukan saat melakukan download browser terautentikasi; upaya untuk menggunakan pengalihan HTTP ke HTTPS.

Akses ke objek publik

Semua permintaan ke storage.cloud.google.com URI memerlukan autentikasi. Hal ini berlaku meskipun allUsers memiliki izin untuk mengakses objek. Jika Anda ingin pengguna mendownload objek yang dapat diakses secara anonim tanpa mengautentikasi, gunakan endpoint path-style XML API:

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

Untuk mengetahui detail dan contohnya, lihat Mengakses Data Publik.

Dukungan TLS bersama

• Permintaan JSON API: storage.mtls.googleapis.com

• Download browser terautentikasi: storage.mtls.cloud.google.com

Langkah berikutnya

• Mengupload file ke Cloud Storage.
• Mendownload file dari Cloud Storage.
• Menghosting situs statis.
• Pelajari opsi untuk mengontrol akses ke data Anda.