リクエストエンドポイント

このページでは、Cloud Storage にアクセスするために使用できるさまざまなリクエストエンドポイントについて説明します。Cloud Storage は、HTTP/1.1、HTTP/2、HTTP/3 プロトコルをサポートしています。エンドポイントは Cloud Storage にアクセスできる場所で、URL として記述されます。

一般的な API リクエスト

JSON API

Cloud Storage に対して直接 JSON API リクエストを送信する場合は、次のエンドポイントを使用します。

オブジェクトのアップロード以外の一般的な JSON API リクエストの場合、次のエンドポイントを使用します。PATH_TO_RESOURCE は適切な値に置き換えます。
```
https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
```
JSON API オブジェクトのアップロードでは、次のエンドポイントを使用します。BUCKET_NAME は適切な値に置き換えます。
```
https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
```
バッチリクエストでは、次のエンドポイントを使用します。PATH_TO_RESOURCE は適切な値に置き換えます。
```
https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE
```
必要に応じて、JSON API オブジェクトのダウンロードで次のエンドポイントを使用できます。BUCKET_NAME と OBJECT_NAME は適切な値に置き換えてください。
```
https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
```

JSON API エンドポイントでは、HTTPS リクエストのみ受け入れられます。

XML API

Cloud Storage に直接 XML API リクエストを送信する場合は、仮想ホスト形式またはパス形式のエンドポイントを使用します。BUCKET_NAME と OBJECT_NAME は適切な値に置き換えます。

仮想ホスト形式のエンドポイント:

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

パス形式のエンドポイント:

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

XML API エンドポイントでは、SSL（Secure Sockets Layer）暗号化がサポートされているため、HTTP または HTTPS のいずれかを使用できます。HTTPS の使用をおすすめします。特に、Cloud Storage に対して OAuth 2.0 を使用して認証する場合は、この方法をおすすめします。

プロキシ経由で接続する場合におすすめする方法については、トラブルシューティングをご覧ください。

URL パス部分のエンコード

バケットの命名とオブジェクトの命名に関する一般的な考慮事項に加えて、Cloud Storage ツール間の互換性を確保するために、リクエスト URL のオブジェクト名またはクエリ文字列に表示される次の文字をエンコードする必要があります。

!、#、$、&、'、(、)、*、+、,、/、:、;、=、?、@、[、]、スペース文字。

たとえば、バケット example-bucket 内の foo??bar という名前のオブジェクトに対する JSON API GET リクエストを送信する場合、リクエスト URL は次のようになります。

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

あらゆるシナリオですべての文字をエンコードする必要はありません。さらに、エンコードは通常クライアントライブラリ（Cloud Storage クライアントライブラリなど）によって処理されるため、このようなツールの使用時には、未加工のオブジェクト名を渡すことができます。

percent-encoding の使用方法の詳細については、RFC 3986 の Section 3.3 Path をご覧ください。

Google Cloud コンソールエンドポイント

Google Cloud コンソールを使用する場合は、次の URL を使用してさまざまなリソースにアクセスします。

リソース	URL
プロジェクトのバケットリスト	`https://console.cloud.google.com/storage/browser?project=PROJECT_ID`
バケットのオブジェクトリスト	`https://console.cloud.google.com/storage/browser/BUCKET_NAME`
オブジェクトの詳細	`https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME`
オブジェクトのデータ	認証済みのブラウザでのダウンロードをご覧ください。

gcloud エンドポイント

gcloud storage コマンドは、JSON API エンドポイントを使用します。エンドポイントの使用は gcloud CLI によって管理されます。

クライアントライブラリエンドポイント

Cloud Storage クライアントライブラリは、リクエストエンドポイントを自動的に管理します。必要に応じて、リクエストエンドポイントを手動で設定できます。これは、特定のエンドポイントを使用する場合や、テキスト目的でローカルエミュレータを使用する場合などに便利です。

C++

詳細については、Cloud Storage C++ API のリファレンスドキュメントをご覧ください。

Cloud Storage に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

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 のリファレンスドキュメントをご覧ください。


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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。


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 のリファレンスドキュメントをご覧ください。

/**
 * 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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。


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 のリファレンスドキュメントをご覧ください。

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

カスタムドメイン

独自のドメインを所有している場合は、Cloud Storage バケットなどの 1 つ以上の Google Cloud サービスに URI をマッピングできます。この「バケットにバインドされたホスト名」という用語が、この Cloud Storage リクエストエンドポイントを説明する際に使用されることがあります。カスタムドメインを Cloud Storage バケットに接続するには、DNS レコードに A または CNAME リダイレクトを作成します。

`A` レコード

通常、カスタムドメインを Cloud Storage バケットに接続する場合は、A レコードを使用します。

A レコードは HTTPS リクエストをサポートします。
A レコードは、単一のホスト名から複数のバケットや、他の Google Cloud サービスにトラフィックを送信するために使用できます。
A レコードでは、バケット名に対して制限を設けません。

A レコードを使用する場合は、Google Cloud リソースに追加の設定を行って使用する必要があります。A レコードでカスタムドメインを使用するためのガイドとして、ロードバランサと SSL 証明書の設定をご覧ください。

`CNAME` レコード

カスタムドメインを Cloud Storage バケットに接続する場合は、CNAME レコードを使用できますが、一定の制限事項があります。

CNAME レコードでは、HTTP リクエストしかサポートされません。
CNAME レコードでは、特定のホスト名から 1 つのバケットにしかトラフィックを転送できません。
CNAME レコードでは、ホスト名と、対応させる関連バケット名が必要です。また、バケット名は検証する必要があります。
CNAME レコードは、www.mydomain.com などのサブドメインにのみ使用できます。mydomain.com などのトップレベルドメインには使用できません。

CNAME レコードを使用する場合は、CNAME レコードのホスト名の部分を次のように設定する必要があります。

c.storage.googleapis.com.

たとえば、ドメインが example.com で、ユーザーにトラベルマップを提供するとします。Cloud Storage に travel-maps.example.com というバケットを作成した後、travel-maps.example.com から Cloud Storage URI にリクエストをリダイレクトする CNAME レコードを DNS に作成できます。そのためには、DNS で次の CNAME レコードを公開します。

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

これで、ユーザーは次の URL を使用してパリの地図にアクセスできます。

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

ご利用のドメイン登録サービスに、CNAME リソースレコードの追加など、ドメインを管理するための手段があるはずです。たとえば、Cloud DNS を使用する場合は、レコードの追加、変更、削除ページでリソースレコードの追加手順を確認できます。

認証によるブラウザでのダウンロード

認証によるブラウザでのダウンロードでは、Cookie ベースの認証を使用します。Cookie ベースの認証では、ユーザーは各自のユーザーアカウントにログインして自分の身元を証明するよう求められます。指定したユーザーアカウントは、オブジェクトをダウンロードするための適切な権限を持っている必要があります。たとえば、Identity and Access Management を使用してオブジェクトへのアクセスを制御する場合、そのユーザーのアカウントは、storage.objects.viewer 権限を持っている必要があります。この権限は、Storage オブジェクト閲覧者ロールで付与されます。

Cookie ベースの認証を使用してオブジェクトをダウンロードするには、次の URL を使用します。BUCKET_NAME と OBJECT_NAME は適切な値に置き換えます。

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

たとえば、バケット example-maps に含まれる画像 london.jpg を共有したとすると、URL は次のようになります。

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

正常にログインすると、リクエストしたコンテンツにリダイレクトされます。このコンテンツの URL は英数字シーケンスで始まり、文字列 /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME を含んでいます。

認証によるブラウザでのダウンロードを行うには、HTTPS を使用する必要があります。HTTPS への HTTP リダイレクトの使用を試みます。

一般公開オブジェクトへのアクセス

storage.cloud.google.com URI へのリクエストでは、すべて認証が必要です。これは、オブジェクトへのアクセス権限が allUsers に付与されている場合でも適用されます。ユーザーが認証なしで匿名でアクセスできるオブジェクトをダウンロードできるようにするには、XML API のパス形式のエンドポイントを使用します。

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

詳細と例については、一般公開データへのアクセスをご覧ください。

相互 TLS のサポート

相互 TLS（mTLS）は、クライアントとサーバーの間で相互認証を行うための業界標準プロトコルです。Cloud Storage は、次の mTLS エンドポイントをサポートしています。

JSON API リクエスト: storage.mtls.googleapis.com
認証によるブラウザでのダウンロード: storage.mtls.cloud.google.com