Bitzsoft.Integrations.FileStorage.GoogleCloud 1.0.0-alpha.10

Bitzsoft.Integrations.FileStorage.GoogleCloud

Google Cloud Storage（GCS）多租户对象存储连接器，提供受控 bucket/prefix、对象元数据、 分页、流式下载、generation 条件删除和可恢复分块上传，支持 net5.0、net8.0 与 net10.0。

安装

dotnet add package Bitzsoft.Integrations.FileStorage.GoogleCloud

已实现能力

• 服务账号 JWT Bearer 与宿主提供的短期 External Access Token；
• 官方 GCS endpoint 和显式可信私有代理；
• 固定 bucket 与 object prefix 边界；
• 对象 metadata get/list 和 opaque page token；
• 固定 generation 的流式完整或 Range 下载；
• CRC32C 完整性校验；
• 已知长度对象的 resumable upload、状态查询、恢复和分块传输；
• ifGenerationMatch=0 仅创建、指定 generation 条件覆盖；
• 指定 generation 的确定性删除和可选 404-as-absent；
• Provider 目录、多租户 endpoint/凭据解析和稳定错误分类。

本包使用 GCS JSON API，不依赖 Google Cloud .NET SDK，也不实现 bucket 管理、ACL/IAM、 签名 URL、Compose/Rewrite、Pub/Sub 通知或对象同步引擎。

凭据与最小权限

ServiceAccountJwt 模式需要：

ServiceAccountEmail
ServiceAccountPrivateKey
ServiceAccountPrivateKeyId   # 可选

ExternalAccessToken 模式需要：

ExternalAccessToken

只读 profile 使用 devstorage.read_only scope；读写 profile 使用 devstorage.read_write scope。IAM 仍应按目标 bucket/prefix 的实际业务范围最小化。 生产宿主必须通过 IIntegrationCredentialResolver 从 Vault/KMS 动态解析凭据； 不要把私钥或 access token 写入配置文件、endpoint profile 或日志。

注册

services.AddBitzsoftGoogleCloudStorage(
    GoogleCloudStorageEndpointProfile.CreateOfficial(
        bucketName: "customer-a-documents",
        objectPrefix: "integrations/",
        authenticationMode:
            GoogleCloudStorageAuthenticationMode.ServiceAccountJwt,
        access: GoogleCloudStorageAccess.ReadWrite));

也可以使用 options：

services.AddBitzsoftGoogleCloudStorage(options =>
{
    options.BucketName = "customer-a-documents";
    options.ObjectPrefix = "integrations/";
    options.Access = GoogleCloudStorageAccess.ReadWrite;
    options.PageSize = 500;
});

不同租户使用不同 bucket、prefix 或代理时，实现 IGoogleCloudStorageEndpointProfileResolver，再调用 AddBitzsoftGoogleCloudStorage<TEndpointProfileResolver>()。

读取与分页

var context = new GoogleCloudStorageRequestContext(
    tenantId: "customer-a",
    profileId: "production",
    credentialName: "gcs-service-account");

var page = await client.ListObjectsAsync(context, cancellationToken: cancellationToken);
var metadata = await client.GetObjectAsync(
    context,
    "orders/2026-07-25.json",
    cancellationToken: cancellationToken);

await using var download = await client.OpenObjectDownloadAsync(
    context,
    metadata.Name,
    new GoogleCloudStorageDownloadOptions(generation: metadata.Generation),
    cancellationToken);

await using var source = await download.OpenBodyStreamAsync(cancellationToken);
await source.CopyToAsync(destination, cancellationToken);

GoogleCloudStorageDownload 持有底层 HTTP response，调用方必须释放；调用方提供的目标流 仍由调用方拥有。Range 下载必须固定正 generation，避免对象被并发替换后拼接出混合内容。

page token 是短期 opaque 值，并绑定 tenant/profile/bucket/prefix/page size。不要解析、 跨租户复用或长期持久化。

可恢复上传

var uploadRequest =
    await GoogleCloudStorageResumableUploadRequest.CreateForSeekableStreamAsync(
        objectName: "orders/2026-07-25.json",
        contentType: "application/json",
        content: source,
        precondition: GoogleCloudStorageGenerationPrecondition.CreateOnly(),
        cancellationToken);

var session = await client.CreateResumableUploadSessionAsync(
    context,
    uploadRequest,
    cancellationToken);

var progress = await client.UploadChunkAsync(
    context,
    session,
    source,
    rangeStart: 0,
    rangeLength: source.Length,
    cancellationToken);

• 分块大小除最后一块外必须满足 256 KiB 量子；
• session URI 是 bearer capability，必须像 secret 一样加密保存、脱敏并设置保留期；
• 恢复 session 时必须同时验证连接器生成的 context binding；
• 非 seekable 流必须由调用方预先提供总长度与完整 CRC32C；
• 客户端不释放调用方上传流；
• 网络结果不确定时，先查询 upload status，再从服务端确认的 offset 继续，不能盲目重传。

条件删除

var result = await client.DeleteObjectAsync(
    context,
    objectName: metadata.Name,
    generation: metadata.Generation,
    options: new GoogleCloudStorageDeleteOptions(
        treatNotFoundAsAlreadyAbsent: true),
    cancellationToken);

删除必须指定读取到的 generation，避免误删同名新版本。AlreadyAbsent 只表示按显式策略 把 404 解释为目标已不存在，不表示本次调用执行了删除。

安全、日志与限制

• 官方 endpoint 强制 HTTPS；自定义 API、上传和 OAuth 主机都必须显式信任；
• object name 必须位于 profile 的固定 prefix 下；
• OAuth/JWT 和 resumable session URI 不进入日志或异常；
• 普通对象正文按流传输，连接器与 RequestLogging 不强制截断或限制大小；
• 错误仅暴露稳定错误码、分类、请求 ID 和安全元数据；
• 写入只有带 generation precondition 时才具有明确并发语义；
• 当前不自动重试创建 upload session、最终分块或删除等可能已生效的写操作。

首次生产接入应在真实 bucket 验证 IAM、CMEK、retention policy、object hold、 versioning、代理 Range 行为、CRC32C 和超大对象分块恢复。合规保留策略可能令删除被拒绝， 宿主不能把授权或保留期错误当成幂等成功。