Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 REST API 建立及管理 Filestore 代理磁碟區

如果您將 Filestore 代理磁碟區與自己的自動化調度管理平台、VM 沙箱或非 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：父項磁碟區集區的 ID。
VOLUME_ID：磁碟區的 ID，與 ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ 相符。

磁碟區佈建作業會在 1 到 2 秒內完成。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：虛擬私有雲網路中 NFS 掛接端點的內部 IP 位址。
mountName：要掛接的 NFS 匯出路徑元件。

掛接磁碟區

佈建磁碟區後，自動調度管理工具可以直接將磁碟區的 NFSv3 匯出項目，掛接至連線至相同虛擬私有雲網路的任何用戶端 VM 或容器主機：

確認主機上已安裝 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：父項磁碟區集區的 ID。
VOLUME_ID：磁碟區的 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"

更新磁碟區配額

如要提高使用中磁碟區的儲存空間配額，請傳送 HTTP PATCH 要求，並指定 updateMask=quotaMib。磁碟區配額只能增加，不支援減少：

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 匯出規則，請傳送 HTTP PATCH 要求，並指定 updateMask=ipAcls：

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 替換為快照的專屬 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"

從快照複製磁碟區

如要依據快照複製磁碟區，來源快照必須來自相同磁碟區集區中的磁碟區。

將 HTTP POST 要求傳送至 volumes:createFromSource 端點。在要求主體中傳遞 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 會變更。請先從已完成的作業回應中擷取更新後的 mountPoint，或呼叫 volumes.get，再重新掛接磁碟區：
```
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 代理磁碟區