请求端点

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

注意：本页面上介绍的 Cloud Storage 网址随时可能更改。

典型的 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 请求。

注意：JSON API 也支持 https://www.googleapis.com 端点，它在对象的 selfLink 元数据字段中返回，但https://storage.googleapis.com 是实现更好性能和可用性的首选端点。同样，https://content-storage.googleapis.com 端点支持下载，并在对象的 mediaLink 元数据字段中返回，但不建议使用。

XML API

重要提示：如果您打算通过浏览器传送内容，请注意，XML API 会从请求端点所对应的来源传送内容。如果您需要从某个独有来源传送内容，请考虑使用 JSON 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) 加密，这意味着您可以使用 HTTP 或 HTTPS。建议使用 HTTPS（尤其是在使用 OAuth 2.0 向 Cloud Storage 进行authenticate时）。

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

对网址路径部分编码

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

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

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

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

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

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

Google Cloud 控制台端点

使用 Google Cloud 控制台时，您可以使用以下网址访问各种资源：

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

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 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

using Google.Cloud.Storage.V1;
using System;

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) = new St>orageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

/**
 * 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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

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

自定义网域

如果您拥有自己的网域，则可以将其 URI 映射到一项或多项 Google Cloud 服务（包括 Cloud Storage 存储桶）。术语“存储桶绑定主机名”有时用于描述此 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 记录只能将来自指定主机名的流量定向到单个存储桶。
• CNAME 记录要求主机名和关联的存储桶名称匹配，并且您必须验证存储桶名称。
• CNAME 记录只能用于子网域（例如 www.mydomain.com），但不能用于顶级网域（例如 mydomain.com）。

使用 CNAME 记录时，必须将 CNAME 记录的主机名部分设置为以下内容：

c.storage.googleapis.com.

例如，假设您的网域是 example.com，并且您希望为您的客户提供旅行地图。您可以在 Cloud Storage 中创建一个名为 travel-maps.example.com 的存储桶，然后在 DNS 中创建 CNAME 记录，将请求从 travel-maps.example.com 重定向到 Cloud Storage URI。为此，您在 DNS 中发布以下 CNAME 记录：

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

如此操作之后，您的客户便可以使用以下网址访问巴黎的地图：

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

您使用的域名注册服务应具备适当的方法，便于您管理域名（包括添加 CNAME 资源记录）。例如，如果您使用 Cloud DNS，则可以在添加、修改和删除记录页面上找到添加资源记录的说明。

经过身份验证的浏览器下载

基于身份验证的浏览器下载使用基于 Cookie 的身份验证。基于 Cookie 的身份验证要求用户登录其用户账号以确定他们的身份。指定的账号必须拥有适当的权限才能下载对象。例如，如果您使用 Identity and Access Management 控制对象的访问权限，则用户的账号应拥有 storage.objects.viewer 权限，该权限是 Storage Object Viewer 角色授予的。

要使用基于 Cookie 的身份验证下载对象，请使用以下网址，并将 BUCKET_NAME 和 OBJECT_NAME 替换为适当的值：

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

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

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

成功登录后，您会被重定向到所请求的内容。此内容的网址以字母数字序列开头且包含字符串 /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME

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

重要提示：如果您已启用数据访问审核日志来跟踪对象的访问权限，除非对象可公开访问或是在 Google Cloud 控制台中完成访问，否则用户无法使用经过身份验证的浏览器下载来访问对象。如需了解详情，请参阅“问题排查”主题。

访问公开对象

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

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

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

后续步骤

• 将文件上传到 Cloud Storage。
• 从 Cloud Storage 下载文件。
• 托管静态网站。
• 了解用于控制数据的访问权限的选项。