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

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.

XML API

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

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

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:

Langkah selanjutnya