Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 REST API 创建和管理 Filestore 智能体存储卷

如果您将 Filestore 智能体存储卷与自己的编排平台、基于虚拟机的沙盒或非 Google Kubernetes Engine (GKE) 容器环境搭配使用，则可以使用 Filestore REST API 直接在存储卷池中预配和管理各个存储卷。

准备工作

在设置 Filestore 智能体存储卷中完成初始项目和 Private Service Connect (PSC) 网络设置。
在创建和管理卷池中创建区域级卷池。

创建卷

REST API

如需在卷池中预配单个卷，请向 volumes.create 端点发送 HTTP POST 请求：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes?volumeId=VOLUME_ID" \
  -d '{
    "description": "Dynamic tool scratchpad for Agent Worker 12",
    "labels": {
      "agent_id": "worker-12",
      "workflow": "code_eval"
    }
  }'

替换以下内容：

PROJECT_ID： Google Cloud 项目 ID。
LOCATION：包含父级卷池的区域，例如 us-central1。
VOLUME_POOL_ID：父级卷池的标识符。
VOLUME_ID：卷的标识符，与 ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ 匹配。

卷预配会在一到两秒内完成。该 API 会直接返回 Volume 资源。您还可以在创建卷期间指定自定义卷配额 (quotaMib) 和动态 NFS 导出选项 (ipAcls)：

{
  "name": "projects/my-project/locations/us-central1/volumePools/my-volume-pool/volumes/my-volume",
  "description": "Dynamic tool scratchpad for Agent Worker 12",
  "mountPoint": {
    "ipAddress": "10.128.0.45",
    "mountName": "my_volume"
  }
}

请注意 mountPoint 中返回的值：

ipAddress：VPC 网络中 NFS 装载端点的内部 IP 地址。
mountName：要装载的 NFS 导出路径组件。

装载卷

预配卷后，编排器可以将卷的 NFSv3 导出直接装载到连接到同一 VPC 网络的任何客户端虚拟机或容器主机上：

确保主机上已安装 NFS 客户端实用程序（例如，Debian 或 Ubuntu 上的 nfs-common）。
使用卷的 mountPoint 中返回的 ipAddress 和 mountName 创建装载目录并装载卷：
```
sudo mkdir -p MOUNT_DIR
sudo mount -t nfs -o vers=3,proto=tcp,mountproto=tcp,port=2049,mountport=2050 \
    IP_ADDRESS:/MOUNT_NAME MOUNT_DIR
```
替换以下内容：
- MOUNT_DIR：装载卷的本地目录路径，例如 /workspace。
- IP_ADDRESS：创建或检索卷时返回的 mountPoint.ipAddress 值。
- MOUNT_NAME：创建或检索卷时返回的 mountPoint.mountName 值。

管理卷

REST API

在以下每个请求中，替换：

PROJECT_ID： Google Cloud 项目 ID。
LOCATION：包含父级卷池的区域。
VOLUME_POOL_ID：父级卷池的标识符。
VOLUME_ID：卷的标识符。

获取卷详情

如需查看现有卷的详细信息（包括其 mountPoint 和当前生命周期 state），请执行以下操作：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

列出池中的卷

如需列出卷池中预配的所有卷，请运行以下命令：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes"

更新卷配额

如需增加活跃卷的存储空间配额，请发送指定 updateMask=quotaMib 的 HTTP PATCH 请求。卷配额只能增加，不支持减少卷配额：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "quotaMib": 4096
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=quotaMib"

更新卷 IP ACL

如需将 NFS 访问权限限制为特定沙盒客户端 IP 地址或更新 IP 导出规则，请发送指定 updateMask=ipAcls 的 HTTP PATCH 请求：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.50/32"],
        "accessMode": "READ_WRITE"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=ipAcls"

删除卷

当智能体会话结束或临时沙盒终止时，请删除卷以回收池中的配额：

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

使用卷快照克隆工作区

如果您已有处于 READY 状态的卷池，并且现有源卷处于 HOT 状态，则可以创建卷快照来捕获智能体存储卷的时间点状态，以便日后克隆或分支工作区。

REST API

创建卷快照

向 backups.create 端点发送 HTTP POST 请求，在 sourceVolume 字段中指定卷的完整资源名称，并将 SNAPSHOT_ID 替换为快照的唯一标识符：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVolume": "projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID",
    "description": "Baseline workspace snapshot"
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/backups?backupId=SNAPSHOT_ID"

该请求会返回一个长时间运行的操作 (LRO)。在从快照克隆卷之前，请轮询操作或查询快照资源，直到其 state 为 READY：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/backups/SNAPSHOT_ID"

从快照克隆卷

如需通过快照克隆卷，来源快照必须来自同一卷池中的卷。

向 volumes:createFromSource 端点发送 HTTP POST 请求。在请求正文中传递 ipAcls，以配置导出权限并在 HOT 层级中激活克隆的卷：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "backup": "projects/PROJECT_ID/locations/LOCATION/backups/SNAPSHOT_ID",
    "volumeId": "CLONED_VOLUME_ID",
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.0/24"],
        "accessMode": "READ_WRITE",
        "squashMode": "NO_ROOT_SQUASH"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes:createFromSource"

替换以下内容：

SNAPSHOT_ID：同一卷池中来源快照的 ID。
CLONED_VOLUME_ID：新克隆卷的 ID。

该请求会返回一个长时间运行的操作。轮询操作，直到 done 为 true：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

操作完成后，调用 volumes.get（或检查已完成的操作响应），以在装载之前检索新卷的 mountPoint（ipAddress 和 mountName）：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/CLONED_VOLUME_ID"

从快照克隆卷的速度为每 GB 3 秒或每 10,000 个文件 1.5 秒。

将卷分层到 COLD

REST API

如需将空闲工作区分层到冷存储，请发送 HTTP PATCH 请求，将卷状态更新为 COLD 并清除 ipAcls：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "COLD",
    "ipAcls": []
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=state,ipAcls"

如需在代理会话恢复时将卷从 COLD 层级恢复到 HOT 层级，请执行以下操作：

调用 unfreeze 自定义方法，在请求正文中传递 ipAcls，以配置客户端访问权限并在 HOT 层级中激活卷的装载点：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.0/24"],
        "accessMode": "READ_WRITE",
        "squashMode": "NO_ROOT_SQUASH"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID:unfreeze"

该请求会返回一个长时间运行的操作。轮询操作，直到 done 为 true：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

从 COLD 层级恢复卷时，Filestore 会从卷池中分配一个新的 NFS 装载端点，因此 mountPoint.ipAddress 和 mountPoint.mountName 会发生变化。在重新装载卷之前，从已完成的操作响应中或通过调用 volumes.get 检索更新后的 mountPoint：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"
```

后续步骤

管理和监控卷池。
为 Filestore 智能体存储卷配置 GKE 环境。

使用 REST API 创建和管理 Filestore 智能体存储卷 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

创建卷

REST API

装载卷

管理卷

REST API

获取卷详情

列出池中的卷

更新卷配额

更新卷 IP ACL

删除卷

使用卷快照克隆工作区

REST API

创建卷快照

从快照克隆卷

将卷分层到 COLD

REST API

后续步骤

使用 REST API 创建和管理 Filestore 智能体存储卷