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.

Catatan: URL Cloud Storage yang dijelaskan di halaman ini dapat berubah sewaktu-waktu.

Permintaan API biasa

JSON API

Saat membuat permintaan JSON API secara langsung ke Cloud Storage, gunakan endpoint berikut:

• Untuk permintaan JSON API umum, kecuali upload objek, gunakan endpoint berikut, dengan menggantikan PATH_TO_RESOURCE dengan nilai yang sesuai:

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

• Untuk upload objek JSON API, gunakan endpoint berikut, dengan mengganti BUCKET_NAME dengan nilai yang sesuai:

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

• Untuk permintaan batch, gunakan endpoint berikut, dengan mengganti PATH_TO_RESOURCE dengan nilai yang sesuai:

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

• Jika ingin, untuk download objek JSON API, Anda dapat menggunakan endpoint berikut, dengan mengganti BUCKET_NAME dan OBJECT_NAME dengan nilai yang sesuai:

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

Endpoint API JSON hanya menerima permintaan HTTPS.

Catatan: Endpoint https://www.googleapis.com juga didukung untuk JSON API dan ditampilkan dalam kolom metadata selfLink untuk sebuah objek, tetapi https://storage.googleapis.com adalah endpoint yang dipilih untuk mendapatkan performa dan ketersediaan yang lebih baik. Demikian pula, endpoint https://content-storage.googleapis.com didukung untuk download dan ditampilkan di metadata mediaLink untuk suatu objek, tetapi juga tidak direkomendasikan untuk digunakan.

XML API

Penting: Jika Anda ingin menayangkan konten melalui browser, perlu diperhatikan bahwa XML API menayangkan konten dari asal yang sama dengan endpoint permintaan. Jika Anda perlu menyajikan konten dari asal yang unik, pertimbangkan untuk menggunakan JSON API atau Download browser terautentikasi.

Saat membuat permintaan XML API secara langsung ke Cloud Storage, gunakan endpoint virtual host-style atau path-style, dengan mengganti BUCKET_NAME dan OBJECT_NAME dengan nilai yang sesuai:

• Endpoint virtual hosted-style:

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

• Endpoint path-style

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

Catatan: Endpoint virtual hosted-style tidak dapat digunakan untuk mengakses bucket bernama domain. Gunakan endpoint path-style atau pengalihan.

Endpoint API XML mendukung enkripsi secure sockets layer (SSL), yang berarti Anda dapat menggunakan HTTP atau HTTPS. Sebaiknya gunakan HTTPS, terutama jika Anda melakukan autentikasi ke Cloud Storage menggunakan OAuth 2.0.

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 informasi selengkapnya tentang penggunaan enkode persen, lihat Bagian 3.3 Path di RFC 3986.

Endpoint konsol Google Cloud

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

Resource	URL
Daftar bucket untuk project	https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Daftar objek untuk bucket	https://console.cloud.google.com/storage/browser/BUCKET_NAME
Detail untuk objek	https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
Data untuk objek	Lihat Download browser terautentikasi

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:

C++

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Cloud Storage C++ API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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#

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

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

Go

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Node.js API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

/**
 * 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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage PHP API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Python API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Ruby API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

# 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 layanan Google 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 untuk 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 dimulai dengan urutan alfanumerik dan berisi string /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

Mutual TLS (mTLS) adalah protokol standar industri untuk autentikasi timbal balik antara klien dan server. Cloud Storage mendukung endpoint mTLS berikut:

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

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

Langkah selanjutnya

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