更新 SFTP 使用者的 bucket

本文說明如何更新 Cloud FTP 使用者的 Cloud Storage bucket，包括使用者可存取的 bucket 和擁有的權限。

大致步驟如下：

1. 更新使用者服務帳戶的 IAM 角色。
2. 將使用者的目錄對應至更新後的 bucket。

事前準備

• 建立一或多個 Cloud Storage bucket，用於儲存使用者要處理的資料 (如果 bucket 尚不存在)。您最多可以授予使用者 10 個 bucket 的存取權。

必要的角色

如要取得更新 SFTP 使用者所需的權限，請要求管理員授予您專案的 FTP 管理員 (roles/ftp.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 ftp.users.update 權限，可更新 SFTP 使用者。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

更新使用者服務帳戶的 IAM 角色

如果您變更使用者可存取的 bucket，或變更使用者對現有目錄對應的權限，則必須使用相關 IAM 角色更新使用者的服務帳戶。請執行下列步驟：

1. 取得使用者服務帳戶的電子郵件地址。如需相關步驟，請參閱「取得使用者的詳細資料」。

2. 如要在目錄對應中新增值區，或增加現有值區的存取權，請按照下列步驟操作：

   1. 如果您尚未具備 Storage bucket 檢視者 (roles/storage.bucketViewer) 角色，請為自己授予該角色：

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
          --member="user:ADMINISTRATOR_EMAIL" \
          --role="roles/storage.bucketViewer"

      更改下列內容：

      • ADMINISTRATOR_EMAIL：建立 SFTP 使用者的主體電子郵件地址。如果您要建立使用者 (而非應用程式)，這個值就是您用來存取 Google Cloud的電子郵件地址。

      • BUCKET_NAME：bucket 的名稱。

   2. 如果沒有 bucket 的「Storage 物件檢視者」角色 (roles/storage.objectViewer)，請授予自己該角色：

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
          --member="user:ADMINISTRATOR_EMAIL" \
          --role="roles/storage.objectViewer"

   3. 將存取 bucket 所需的 IAM 角色授予使用者的服務帳戶：

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
        --member="serviceAccount:SERVICE_ACCOUNT" \
        --role="ROLE_TO_GRANT"

      更改下列內容：

      • SERVICE_ACCOUNT：使用者服務帳戶的電子郵件地址。

      • ROLE_TO_GRANT：要授予的 IAM 角色。指定下列其中一個角色：

        • 如需唯讀存取權，請使用 roles/storage.objectViewer 角色。
        • 如需讀取和寫入權限，請使用 roles/storage.objectAdmin 角色。

   4. 針對使用者需要存取的每個 bucket，重複上述步驟。

3. 如果從目錄對應中移除 bucket，或減少現有 bucket 的存取權，請撤銷使用者服務帳戶的存取權：

   gcloud storage buckets remove-iam-policy-binding gs://BUCKET_NAME \
     --member="serviceAccount:SERVICE_ACCOUNT" \
     --role="ROLE_TO_REVOKE"

   將 ROLE_TO_REVOKE 替換為要撤銷的 IAM 角色。

   針對使用者不應再具備存取權的每個值區和 IAM 角色，重複執行這個步驟。

更新使用者的值區

gcloud

如要更新 SFTP 使用者的 bucket，請執行 gcloud alpha storage ftp users update 指令。

注意：您在要求中提供的目錄對應會覆寫所有現有值。

使用下列任何指令資料之前，請先替換以下項目：

• USERNAME：SFTP 使用者的使用者名稱。
• LOCATION_ID：伺服器的位置，例如 us-west1。
• SERVER_ID：伺服器 ID。
• BUCKET_NAME：SFTP 使用者獲准存取的 bucket 名稱，例如 example-bucket。省略 gs://。
• (選用) BUCKET_PREFIX：要設為這個目錄對應根目錄的 bucket 內資料夾路徑。 如果省略 bucket_prefix 屬性，Cloud FTP 會使用 bucket 根目錄。

• DIRECTORY：向 SFTP 使用者顯示的邏輯登陸目錄路徑。例如：/home/uploads。

  如果您對應多個 bucket 或資料夾，請為每個對應提供不重複的目錄路徑。

  系統不支援巢狀邏輯目錄。如果為目錄提供多個對應，請以扁平結構提供目錄，而非巢狀結構。例如，使用 /dir1 和 /dir2，而不是 /dir1 和 /dir1/dir2。

• SFTP_PERMISSION：目錄的存取層級。如要授予唯讀存取權，請將這個值設為 READ_ONLY。如要取得讀取和寫入權限，請將這個值設為 READ_WRITE。

如要授予使用者多個 bucket 的存取權，請多次提供 --storage-directory-mapping 旗標，並為每個 bucket 提供目錄對應。

執行下列指令：

Linux、macOS 或 Cloud Shell

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，初始化 Google Cloud CLI 並設定驗證和專案。

gcloud alpha storage ftp users update USERNAME --location=LOCATION_ID \
    --server=SERVER_ID \
    --storage-directory-mapping=bucket=BUCKET_NAME,bucket_prefix=BUCKET_PREFIX,directory=DIRECTORY,permission=SFTP_PERMISSION

Windows (PowerShell)

注意：請務必執行 gcloud init，或 gcloud auth login 和 gcloud config set project，初始化 Google Cloud CLI 並設定驗證和專案。

gcloud alpha storage ftp users update USERNAME --location=LOCATION_ID `
    --server=SERVER_ID `
    --storage-directory-mapping=bucket=BUCKET_NAME,bucket_prefix=BUCKET_PREFIX,directory=DIRECTORY,permission=SFTP_PERMISSION

Windows (cmd.exe)

注意： 請執行下列任一指令，確保已透過驗證和專案初始化 Google Cloud CLI： gcloud init； 或 gcloud auth login 和 gcloud config set project。

gcloud alpha storage ftp users update USERNAME --location=LOCATION_ID ^
    --server=SERVER_ID ^
    --storage-directory-mapping=bucket=BUCKET_NAME,bucket_prefix=BUCKET_PREFIX,directory=DIRECTORY,permission=SFTP_PERMISSION

系統會在幾秒內更新使用者。

如果使用者有使用中的 SFTP 連線，可能需要中斷連線再重新連線，更新後的 bucket 設定才會生效。

REST

如要更新 SFTP 使用者的 bucket，請使用 servers.users.patch 方法。在 updateMask 查詢參數中，提供 storageDirectoryMappings 欄位。

注意：您在要求中提供的目錄對應會覆寫所有現有值。

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID：伺服器的 Google Cloud 專案 ID。
• LOCATION_ID：伺服器的位置，例如 us-west1。
• SERVER_ID：伺服器 ID。
• USERNAME：SFTP 使用者的使用者名稱。
• BUCKET_NAME：SFTP 使用者獲准存取的 bucket 名稱，例如 example-bucket。省略 gs://。
• (選用) BUCKET_PREFIX：要在 bucket 中設為這個目錄對應根目錄的資料夾路徑。如果省略這個值，Cloud FTP 會使用 bucket 根目錄。

• DIRECTORY：向 SFTP 使用者顯示的邏輯到達目錄路徑。例如：/home/uploads。如果省略這個值，Cloud FTP 會將登陸目錄設為 /。

  如果您對應多個 bucket 或資料夾，請為每個對應提供不重複的目錄路徑。

  系統不支援巢狀邏輯目錄。如果為目錄提供多個對應，請以扁平結構提供目錄，而非巢狀結構。例如，使用 /dir1 和 /dir2，而不是 /dir1 和 /dir1/dir2。

• SFTP_PERMISSION：目錄的存取層級。如要授予唯讀存取權，請將這個值設為 READ_ONLY。如要取得讀取和寫入權限，請將這個值設為 READ_WRITE。

如要授予使用者多個 bucket 的存取權，請在 storageDirectoryMappings 清單中提供多個 bucket 對應。

HTTP 方法和網址：

PATCH https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID/users/USERNAME?updateMask=storageDirectoryMappings

JSON 要求主體：

{
  "storageDirectoryMappings": [
    {
      "bucket": "BUCKET_NAME",
      "bucketPrefix": "BUCKET_PREFIX",
      "directory": "DIRECTORY",
      "permission": "SFTP_PERMISSION"
    }
  ]
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID/users/USERNAME?updateMask=storageDirectoryMappings"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID/users/USERNAME?updateMask=storageDirectoryMappings" | Select-Object -Expand Content

回應會指出長時間執行的作業。 系統會在幾秒內更新使用者。 <0x

如果使用者有使用中的 SFTP 連線，可能需要中斷連線再重新連線，更新後的 bucket 設定才會生效。

用戶端程式庫

C#

如要瞭解如何安裝及使用 Cloud FTP 的用戶端程式庫，請參閱「Cloud FTP 用戶端程式庫」。詳情請參閱「Cloud FTP C# API 參考文件」。

如要向 Cloud FTP 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

using Google.Cloud.Ftp.V1;
using Google.LongRunning;
using Google.Protobuf.WellKnownTypes;
using System.Threading.Tasks;

public sealed partial class GeneratedCloudFtpClientSnippets
{
    /// <summary>Snippet for UpdateUserAsync</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task UpdateUserAsync()
    {
        // Create client
        CloudFtpClient cloudFtpClient = await CloudFtpClient.CreateAsync();
        // Initialize request argument(s)
        User user = new User();
        FieldMask updateMask = new FieldMask();
        // Make the request
        Operation<User, OperationMetadata> response = await cloudFtpClient.UpdateUserAsync(user, updateMask);

        // Poll until the returned long-running operation is complete
        Operation<User, OperationMetadata> completedResponse = await response.PollUntilCompletedAsync();
        // Retrieve the operation result
        User result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<User, OperationMetadata> retrievedResponse = await cloudFtpClient.PollOnceUpdateUserAsync(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            User retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

如要瞭解如何安裝及使用 Cloud FTP 的用戶端程式庫，請參閱「Cloud FTP 用戶端程式庫」。詳情請參閱 Cloud FTP Go API 參考文件。

如要向 Cloud FTP 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。

//go:build examples

package main

import (
	"context"

	ftp "cloud.google.com/go/ftp/apiv1"
	ftppb "cloud.google.com/go/ftp/apiv1/ftppb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := ftp.NewCloudFtpRESTClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &ftppb.UpdateUserRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/ftp/apiv1/ftppb#UpdateUserRequest.
	}
	op, err := c.UpdateUser(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

如要瞭解如何安裝及使用 Cloud FTP 的用戶端程式庫，請參閱「Cloud FTP 用戶端程式庫」。詳情請參閱「Cloud FTP Java API 參考文件」。

如要向 Cloud FTP 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。

import com.google.api.core.ApiFuture;
import com.google.cloud.ftp.v1.CloudFtpClient;
import com.google.cloud.ftp.v1.UpdateUserRequest;
import com.google.cloud.ftp.v1.User;
import com.google.longrunning.Operation;
import com.google.protobuf.FieldMask;

public class AsyncUpdateUser {

  public static void main(String[] args) throws Exception {
    asyncUpdateUser();
  }

  public static void asyncUpdateUser() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (CloudFtpClient cloudFtpClient = CloudFtpClient.create()) {
      UpdateUserRequest request =
          UpdateUserRequest.newBuilder()
              .setUpdateMask(FieldMask.newBuilder().build())
              .setUser(User.newBuilder().build())
              .build();
      ApiFuture<Operation> future = cloudFtpClient.updateUserCallable().futureCall(request);
      // Do something.
      Operation response = future.get();
    }
  }
}

Node.js

如要瞭解如何安裝及使用 Cloud FTP 的用戶端程式庫，請參閱「Cloud FTP 用戶端程式庫」。詳情請參閱「Cloud FTP Node.js API 參考文件」。

如要向 Cloud FTP 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Optional. Field mask is used to specify the fields to be overwritten in the
 *  User resource by the update.
 *  The fields specified in the update_mask are relative to the resource, not
 *  the full request. A field will be overwritten if it is in the mask. If the
 *  user does not provide a mask then all fields present in the request will be
 *  overwritten.
 */
// const updateMask = {}
/**
 *  Required. The resource being updated
 */
// const user = {}

// Imports the Ftp library
const {CloudFtpClient} = require('@google-cloud/ftp').v1;

// Instantiates a client
const ftpClient = new CloudFtpClient();

async function callUpdateUser() {
  // Construct request
  const request = {
    user,
  };

  // Run request
  const [operation] = await ftpClient.updateUser(request);
  const [response] = await operation.promise();
  console.log(response);
}

callUpdateUser();

PHP

如要瞭解如何安裝及使用 Cloud FTP 的用戶端程式庫，請參閱「Cloud FTP 用戶端程式庫」。詳情請參閱 Cloud FTP PHP API 參考文件。

如要向 Cloud FTP 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。

use Google\ApiCore\ApiException;
use Google\ApiCore\OperationResponse;
use Google\Cloud\Ftp\V1\Client\CloudFtpClient;
use Google\Cloud\Ftp\V1\StorageDirectoryMapping;
use Google\Cloud\Ftp\V1\StorageDirectoryMapping\Permission;
use Google\Cloud\Ftp\V1\UpdateUserRequest;
use Google\Cloud\Ftp\V1\User;
use Google\Cloud\Ftp\V1\UserCredential;
use Google\Cloud\Ftp\V1\UserCredential\Type;
use Google\Rpc\Status;

/**
 * Updates the parameters of a single User.
 *
 * @param string $userCustomerServiceAccount             Service account in customer project attached to this SFTP User.
 * @param string $userUserCredentialsCredentialName      Name of the user credential.
 * @param int    $userUserCredentialsCredentialType      Type of credential.
 * @param string $userStorageDirectoryMappingsBucket     Name of the bucket.
 * @param string $userStorageDirectoryMappingsDirectory  Directory where the user lands in the SFTP server.
 * @param int    $userStorageDirectoryMappingsPermission Permission to the bucket.
 */
function update_user_sample(
    string $userCustomerServiceAccount,
    string $userUserCredentialsCredentialName,
    int $userUserCredentialsCredentialType,
    string $userStorageDirectoryMappingsBucket,
    string $userStorageDirectoryMappingsDirectory,
    int $userStorageDirectoryMappingsPermission
): void {
    // Create a client.
    $cloudFtpClient = new CloudFtpClient();

    // Prepare the request message.
    $userCredential = (new UserCredential())
        ->setCredentialName($userUserCredentialsCredentialName)
        ->setCredentialType($userUserCredentialsCredentialType);
    $userUserCredentials = [$userCredential];
    $storageDirectoryMapping = (new StorageDirectoryMapping())
        ->setBucket($userStorageDirectoryMappingsBucket)
        ->setDirectory($userStorageDirectoryMappingsDirectory)
        ->setPermission($userStorageDirectoryMappingsPermission);
    $userStorageDirectoryMappings = [$storageDirectoryMapping];
    $user = (new User())
        ->setCustomerServiceAccount($userCustomerServiceAccount)
        ->setUserCredentials($userUserCredentials)
        ->setStorageDirectoryMappings($userStorageDirectoryMappings);
    $request = (new UpdateUserRequest())
        ->setUser($user);

    // Call the API and handle any network failures.
    try {
        /** @var OperationResponse $response */
        $response = $cloudFtpClient->updateUser($request);
        $response->pollUntilComplete();

        if ($response->operationSucceeded()) {
            /** @var User $result */
            $result = $response->getResult();
            printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString());
        } else {
            /** @var Status $error */
            $error = $response->getError();
            printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $userCustomerServiceAccount = '[CUSTOMER_SERVICE_ACCOUNT]';
    $userUserCredentialsCredentialName = '[CREDENTIAL_NAME]';
    $userUserCredentialsCredentialType = Type::TYPE_UNSPECIFIED;
    $userStorageDirectoryMappingsBucket = '[BUCKET]';
    $userStorageDirectoryMappingsDirectory = '[DIRECTORY]';
    $userStorageDirectoryMappingsPermission = Permission::PERMISSION_UNSPECIFIED;

    update_user_sample(
        $userCustomerServiceAccount,
        $userUserCredentialsCredentialName,
        $userUserCredentialsCredentialType,
        $userStorageDirectoryMappingsBucket,
        $userStorageDirectoryMappingsDirectory,
        $userStorageDirectoryMappingsPermission
    );
}

Python

如要瞭解如何安裝及使用 Cloud FTP 的用戶端程式庫，請參閱「Cloud FTP 用戶端程式庫」。詳情請參閱 Cloud FTP Python API 參考文件。

如要向 Cloud FTP 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import ftp_v1


def sample_update_user():
    # Create a client
    client = ftp_v1.CloudFtpClient()

    # Initialize request argument(s)
    user = ftp_v1.User()
    user.customer_service_account = "customer_service_account_value"
    user.user_credentials.credential_name = "credential_name_value"
    user.user_credentials.credential_type = "PUBLIC_KEY"
    user.storage_directory_mappings.bucket = "bucket_value"
    user.storage_directory_mappings.directory = "directory_value"
    user.storage_directory_mappings.permission = "READ_WRITE"

    request = ftp_v1.UpdateUserRequest(
        user=user,
    )

    # Make the request
    operation = client.update_user(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

如要瞭解如何安裝及使用 Cloud FTP 的用戶端程式庫，請參閱「Cloud FTP 用戶端程式庫」。詳情請參閱 Cloud FTP Ruby API 參考文件。

如要向 Cloud FTP 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

require "google/cloud/ftp/v1"

##
# Snippet for the update_user call in the CloudFtp service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::Ftp::V1::CloudFtp::Rest::Client#update_user.
#
def update_user
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::Ftp::V1::CloudFtp::Rest::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::Ftp::V1::UpdateUserRequest.new

  # Call the update_user method.
  result = client.update_user request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end