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, yang ditulis sebagai URL.

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

Permintaan API biasa

JSON API

Saat membuat permintaan JSON API 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 objek, tetapi https://storage.googleapis.com adalah endpoint yang lebih disukai untuk performa dan ketersediaan yang lebih baik. Demikian pula, endpoint https://content-storage.googleapis.com didukung untuk didownload dan ditampilkan di kolom 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 langsung ke Cloud Storage, gunakan endpoint gaya dihosting virtual atau gaya jalur, dan ganti 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

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 karakter berikut muncul di 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 encoding persen, lihat Bagian 3.3 Jalur 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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan 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);
}

C#

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

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

/**
 * 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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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 mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

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, akun pengguna harus memiliki izin storage.objects.viewer, yang diberikan dalam 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.

Penting: Jika Anda telah mengaktifkan log audit Akses Data untuk melacak akses ke objek, pengguna tidak dapat menggunakan download browser terautentikasi untuk mengakses objek tersebut, kecuali jika objek tersebut dapat diakses secara publik atau aksesnya dilakukan dalam Konsol Google Cloud. Untuk informasi selengkapnya, lihat Topik pemecahan masalah.

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.

Langkah selanjutnya

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