请求端点

本页面介绍了可用于访问 Cloud Storage 的不同请求端点。Cloud Storage 支持 HTTP/1.1、HTTP/2 和 HTTP/3 协议。 端点是可访问 Cloud Storage 的位置,写成网址形式。

典型的 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) 加密,这意味着您可以使用 HTTP 或 HTTPS。建议使用 HTTPS(尤其是在使用 OAuth 2.0 向 Cloud Storage 进行身份验证时)。

gRPC

您可以使用 gRPC(由 S3NS开发的高性能开源通用 RPC 框架)与 Cloud Storage 进行交互。gRPC 客户端会连接到服务端点。对于 Cloud Storage 等Cloud de Confiance by S3NS 服务,这通常是 googleapis.com 网域上的 DNS 地址(例如 storage.googleapis.com),并且使用标准安全端口(例如 443)。使用 gRPC 可以提高性能并提供高效的流式传输功能。

如需使用 gRPC 与 Cloud Storage 进行交互,您需要在 Cloud 客户端库上启用 gRPC。

使用以下支持的语言之一在客户端库中启用 gRPC:

对于通过代理创建的连接,请参阅问题排查主题以查看建议的做法。

对网址路径部分编码

除了存储桶命名对象命名的一般注意事项之外,您还应该在请求网址的对象名称或查询字符串中出现以下字符时对这些字符进行编码,以确保 Cloud Storage 工具之间的兼容性:

!#$&'()*+,/:;=?@[] 和空格字符。

例如,如果您为存储桶 example-bucket 中名为 foo??bar 的对象发送 JSON APIGET 请求,则您的请求网址应为:

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

请注意,并非所有列出的字符在每种情况下都必须编码。此外,编码通常由客户端库(如 Cloud Storage 客户端库)为您处理,因此您可以在使用此类工具时传递原始对象名称。

如需详细了解如何使用百分比编码,请参阅 RFC 3986 中的第 3.3 节“路径”

Cloud de Confiance 控制台端点

使用 Cloud de Confiance 控制台时,您可以使用以下网址访问不同的资源:

资源 网址
项目的存储桶列表 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 endpoints

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 Object Viewer 角色授予的

要使用基于 Cookie 的身份验证下载对象,请使用以下网址,并将 BUCKET_NAMEOBJECT_NAME 替换为适当的值:

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

例如,如果您共享来自存储桶 example-maps 的图片 london.jpg,网址将如下所示:

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

成功登录后,您会被重定向到所请求的内容。此内容的网址采用 https://ALPHANUMERIC_SEQUENCE-apidata.s3nsusercontent.fr/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME 格式。

在执行基于身份验证的浏览器下载时,必须使用 HTTPS;尝试使用 HTTP 会重定向至 HTTPS。

访问公开对象

storage.cloud.google.com URI 发出的所有请求都需要进行身份验证。即使 allUsers 有权访问对象,也需遵守这一要求。如果您希望用户在未经过身份验证的情况下下载可匿名访问的对象,请使用 XML API 路径样式端点:

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

如需了解详情和示例,请参阅访问公开数据

双向 TLS 支持

双向 TLS (mTLS) 是一种业界标准协议,用于在客户端与服务器之间进行双向身份验证。Cloud Storage 支持以下 mTLS 端点:

后续步骤