Memperbarui bucket untuk pengguna SFTP

Dokumen ini menunjukkan cara memperbarui bucket Cloud Storage untuk pengguna Cloud FTP, termasuk bucket yang dapat diakses pengguna dan izin yang dimiliki pengguna.

Secara umum, berikut adalah langkah-langkah untuk memperbarui bucket pengguna:

  1. Perbarui peran IAM untuk akun layanan pengguna.
  2. Petakan direktori pengguna ke bucket yang diperbarui.

Sebelum memulai

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna memperbarui pengguna SFTP, minta administrator untuk memberi Anda peran IAM FTP Admin (roles/ftp.admin) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin ftp.users.update, yang diperlukan untuk memperbarui pengguna SFTP.

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Memperbarui peran IAM untuk akun layanan pengguna

Jika Anda mengubah bucket yang dapat diakses pengguna, atau jika Anda mengubah izin yang dimiliki pengguna untuk pemetaan direktori yang ada, Anda harus memperbarui akun layanan pengguna dengan peran IAM yang relevan. Lakukan hal berikut:

  1. Dapatkan alamat email akun layanan pengguna. Untuk mengetahui langkah-langkahnya, lihat Mendapatkan detail tentang pengguna.

  2. Jika Anda menambahkan bucket baru ke pemetaan direktori atau meningkatkan akses ke bucket yang ada, lakukan hal berikut:

    1. Beri diri Anda sendiri peran Storage Bucket Viewer (roles/storage.bucketViewer) di bucket, jika Anda belum memiliki peran tersebut:

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

      Ganti kode berikut:

      • ADMINISTRATOR_EMAIL: alamat email principal yang membuat pengguna SFTP. Jika Anda membuat pengguna (bukan aplikasi), nilai ini adalah alamat email yang Anda gunakan untuk mengakses Google Cloud.

      • BUCKET_NAME: nama bucket.

    2. Berikan peran Storage Object Viewer (roles/storage.objectViewer) kepada diri Anda sendiri di bucket, jika Anda belum memiliki peran tersebut:

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
          --member="user:ADMINISTRATOR_EMAIL" \
          --role="roles/storage.objectViewer"
    3. Berikan peran IAM yang diperlukan untuk mengakses bucket kepada akun layanan pengguna:

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

      Ganti kode berikut:

      • SERVICE_ACCOUNT: alamat email akun layanan pengguna.
      • ROLE_TO_GRANT: peran IAM yang akan diberikan. Tentukan salah satu peran berikut:

        • Untuk akses hanya baca, gunakan peran roles/storage.objectViewer.
        • Untuk akses baca dan tulis, gunakan peran roles/storage.objectAdmin.
    4. Ulangi langkah sebelumnya untuk setiap bucket yang perlu diakses pengguna.

  3. Jika Anda menghapus bucket dari pemetaan direktori atau mengurangi akses ke bucket yang ada, batalkan akses dari akun layanan pengguna:

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

    Ganti ROLE_TO_REVOKE dengan peran IAM yang ingin Anda cabut.

    Ulangi langkah ini untuk setiap bucket dan peran IAM yang tidak boleh lagi diakses oleh pengguna.

Memperbarui bucket pengguna

gcloud

Untuk memperbarui bucket bagi pengguna SFTP, jalankan perintah gcloud alpha storage ftp users update.

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • USERNAME: nama pengguna SFTP pengguna.
  • LOCATION_ID: lokasi server, seperti us-west1.
  • SERVER_ID: ID server.
  • BUCKET_NAME: nama bucket yang dapat diakses oleh pengguna SFTP, seperti example-bucket. Hilangkan gs://.
  • (Opsional) BUCKET_PREFIX: jalur folder dalam bucket yang akan ditetapkan sebagai direktori root untuk pemetaan direktori ini. Jika Anda menghapus properti bucket_prefix, maka Cloud FTP akan menggunakan root bucket.
  • DIRECTORY: jalur direktori landing logis yang ditampilkan kepada pengguna SFTP. Contoh, /home/uploads.

    Jika Anda memetakan beberapa bucket atau folder, berikan jalur direktori unik untuk setiap pemetaan.

    Direktori logis bertingkat tidak didukung. Jika Anda menyediakan beberapa pemetaan untuk sebuah direktori, sediakan direktori dalam struktur datar, bukan struktur bertingkat. Misalnya, gunakan /dir1 dan /dir2, bukan /dir1 dan /dir1/dir2.

  • SFTP_PERMISSION: tingkat akses untuk direktori. Untuk akses hanya baca, tetapkan nilai ini ke READ_ONLY. Untuk akses baca dan tulis, tetapkan nilai ini ke READ_WRITE.

Untuk memberi pengguna akses ke beberapa bucket, berikan flag --storage-directory-mapping beberapa kali, dengan pemetaan direktori untuk setiap bucket.

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

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 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)

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
Perlu waktu beberapa detik untuk memperbarui pengguna.

Jika pengguna memiliki koneksi SFTP yang aktif, mereka mungkin perlu memutuskan koneksi, lalu menghubungkannya kembali agar setelan bucket yang diperbarui berlaku.

REST

Untuk memperbarui bucket pengguna SFTP, gunakan metode servers.users.patch. Dalam parameter kueri updateMask, berikan kolom storageDirectoryMappings.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud server.
  • LOCATION_ID: lokasi server, seperti us-west1.
  • SERVER_ID: ID server.
  • USERNAME: nama pengguna SFTP.
  • BUCKET_NAME: nama bucket yang aksesnya diberikan kepada pengguna SFTP, seperti example-bucket. Hilangkan gs://.
  • (Opsional) BUCKET_PREFIX: jalur folder dalam bucket yang akan ditetapkan sebagai direktori root untuk pemetaan direktori ini. Jika Anda menghapus nilai ini, Cloud FTP akan menggunakan root bucket.
  • DIRECTORY: jalur direktori landing logis yang ditampilkan kepada pengguna SFTP. Contoh, /home/uploads. Jika Anda menghapus nilai ini, Cloud FTP akan menetapkan direktori landing ke /.

    Jika Anda memetakan beberapa bucket atau folder, berikan jalur direktori unik untuk setiap pemetaan.

    Direktori logis bertingkat tidak didukung. Jika Anda menyediakan beberapa pemetaan untuk sebuah direktori, sediakan direktori dalam struktur datar, bukan struktur bertingkat. Misalnya, gunakan /dir1 dan /dir2, bukan /dir1 dan /dir1/dir2.

  • SFTP_PERMISSION: tingkat akses untuk direktori. Untuk akses hanya baca, tetapkan nilai ini ke READ_ONLY. Untuk akses baca dan tulis, tetapkan nilai ini ke READ_WRITE.

Untuk memberi pengguna akses ke beberapa bucket, berikan beberapa pemetaan bucket dalam daftar storageDirectoryMappings.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons mengidentifikasi operasi yang berjalan lama. Perlu waktu beberapa detik untuk memperbarui pengguna.

Jika pengguna memiliki koneksi SFTP yang aktif, mereka mungkin perlu memutuskan koneksi, lalu menghubungkannya kembali agar setelan bucket yang diperbarui berlaku.

Library klien

C#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud FTP, lihat Library klien Cloud FTP. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API C# Cloud FTP.

Untuk melakukan autentikasi ke Cloud FTP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud FTP, lihat Library klien Cloud FTP. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Go Cloud FTP.

Untuk melakukan autentikasi ke Cloud FTP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.


//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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud FTP, lihat Library klien Cloud FTP. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Java Cloud FTP.

Untuk melakukan autentikasi ke Cloud FTP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud FTP, lihat Library klien Cloud FTP. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Node.js Cloud FTP.

Untuk melakukan autentikasi ke Cloud FTP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

/**
 * 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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud FTP, lihat Library klien Cloud FTP. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API PHP Cloud FTP.

Untuk melakukan autentikasi ke Cloud FTP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud FTP, lihat Library klien Cloud FTP. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Cloud FTP.

Untuk melakukan autentikasi ke Cloud FTP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

# 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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud FTP, lihat Library klien Cloud FTP. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Ruby Cloud FTP.

Untuk melakukan autentikasi ke Cloud FTP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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