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

このページでは、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.s3nsapis.fr/storage/v1/PATH_TO_RESOURCE
  • JSON API オブジェクトのアップロードでは、次のエンドポイントを使用します。BUCKET_NAME は適切な値に置き換えます。

    https://storage.s3nsapis.fr/upload/storage/v1/b/BUCKET_NAME/o
  • バッチ リクエストでは、次のエンドポイントを使用します。PATH_TO_RESOURCE は適切な値に置き換えます。

    https://storage.s3nsapis.fr/batch/storage/v1/PATH_TO_RESOURCE
  • 必要に応じて、JSON API オブジェクトのダウンロードで次のエンドポイントを使用できます。BUCKET_NAMEOBJECT_NAME は適切な値に置き換えてください。

    https://storage.s3nsapis.fr/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

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

XML API

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

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

    https://BUCKET_NAME.storage.s3nsapis.fr/OBJECT_NAME

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

    https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

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

gRPC

S3NSが開発した高パフォーマンスのオープンソース ユニバーサル RPC フレームワークである gRPC を使用して、Cloud Storage を操作できます。gRPC クライアントはサービス エンドポイントに接続します。Cloud Storage などのCloud de Confiance by S3NS サービスの場合、通常は googleapis.com ドメインの DNS アドレス(storage.googleapis.com など)であり、443 などの標準の安全なポートを使用します。gRPC を使用すると、パフォーマンスが向上し、効率的なストリーミング機能を利用できます。

gRPC を使用して Cloud Storage とやり取りするには、Cloud クライアント ライブラリで gRPC を有効にする必要があります。

次のサポートされている言語のいずれかを使用して、クライアント ライブラリで gRPC を有効にします。

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

URL パス部分のエンコード

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

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

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

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

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

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

Cloud de Confiance コンソールのエンドポイント

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

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

gcloud エンドポイント

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

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

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

C++

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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。


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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。


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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。


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

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

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

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

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

Cookie ベースの認証を使用してオブジェクトをダウンロードするには、次の URL を使用します。BUCKET_NAMEOBJECT_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 の形式は https://ALPHANUMERIC_SEQUENCE-apidata.s3nsusercontent.fr/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME です。

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

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

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

https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

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

相互 TLS のサポート

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

次のステップ