Panduan ini menjelaskan cara menggunakan awalan penyertaan dan pengecualian untuk mengontrol file yang ditransfer.
Ringkasan
Storage Transfer Service mendukung pemfilteran data dari sumber Amazon S3, Microsoft Azure Blob Storage, dan Cloud Storage menggunakan awalan. Awalan adalah string karakter di awal jalur yang menentukan kumpulan objek.
Anda dapat menggunakan filter awalan dengan tiga cara:
Sertakan awalan: Hanya objek yang cocok dengan awalan yang ditentukan yang akan ditransfer.
Kecualikan awalan: Objek yang cocok dengan awalan yang ditentukan akan dihilangkan dari transfer.
Keduanya bersama-sama: Anda dapat menggunakan awalan sertakan dan kecualikan secara bersamaan untuk kontrol yang lebih terperinci. Jika digunakan bersama, setiap awalan pengecualian harus dimulai dengan salah satu awalan penyertaan yang ditentukan.
Jika Anda tidak menentukan awalan apa pun, semua objek di bucket sumber akan ditransfer.
Filter awalan dapat digabungkan dengan pola glob, filter waktu terakhir diubah, dan filter kelas penyimpanan S3.
Aturan
Aturan berikut berlaku untuk awalan:
Tidak ada garis miring di awal: Jangan sertakan garis miring di awal awalan. Untuk jalur
s3://my-bucket/logs/2025/requests.gz, awalan yang benar adalahlogs/2025/requests.gz.Kecocokan sebagian: Awalan berfungsi dengan pencocokan sebagian. Misalnya, awalan
pathcocok denganpath_1/danpath_2/.Tidak ada karakter pengganti: Karakter pengganti tidak didukung.
Relatif terhadap folder sumber: Jika sumber transfer Anda menyertakan jalur atau folder, awalan akan relatif terhadap jalur atau folder tersebut. Lihat Interaksi dengan jalur atau folder sumber untuk mengetahui detailnya.
Awalan yang berbeda: Setiap awalan penyertaan harus menentukan bagian unik dari namespace objek. Anda tidak dapat menggunakan awalan penyertaan yang sudah dicakup oleh awalan penyertaan lain. Misalnya, Anda tidak dapat menentukan
data/dandata/reports/sebagai awalan penyertaan. Aturan yang sama berlaku di antara awalan pengecualian.Dependensi awalan pengecualian: Saat menggunakan awalan penyertaan dan pengecualian bersama-sama, setiap awalan pengecualian harus diawali dengan salah satu awalan penyertaan yang ditentukan. Misalnya, jika
pathadalah awalan penyertaan, awalan pengecualian yang valid dapat berupapath/bataupathway. Aturan ini tidak berlaku jika Anda hanya menggunakan awalan pengecualian.Maksimum 1.000 awalan untuk setiap jenis: Satu tugas transfer mendukung hingga 1.000 awalan penyertaan dan hingga 1.000 awalan pengecualian. Anda dapat membagi transfer menjadi beberapa tugas jika diperlukan awalan tambahan.
Untuk informasi umum selengkapnya tentang awalan, lihat Mencantumkan Kunci secara Hierarkis Menggunakan Awalan dan Pemisah dalam dokumentasi Amazon S3 atau Metode daftar objek untuk Cloud Storage.
Interaksi dengan jenis filter lainnya
Saat Anda menggunakan beberapa filter, Storage Transfer Service akan menerapkannya dalam urutan berikut:
- Sertakan awalan: Mempersempit objek yang akan dipertimbangkan.
- Kondisi objek (pola glob, waktu terakhir diubah, dan kelas penyimpanan S3): Memfilter objek yang cocok dengan awalan penyertaan. Objek harus cocok dengan semua kondisi objek yang ditentukan untuk disertakan dalam transfer.
- Kecualikan awalan: Menghapus objek dari hasil.
Pelajari lebih lanjut cara memfilter dengan pola glob, waktu terakhir diubah, dan kelas penyimpanan S3.
Interaksi dengan jalur atau folder sumber
Filter penyertaan dan filter kecualikan bersifat relatif terhadap jalur atau folder apa pun yang Anda tentukan untuk sumber.
Misalnya, jika sumber Anda adalah gs://bucketA/alpha, dan Anda ingin menentukan
filter untuk gs://bucketA/alpha/beta:
Benar
- Jalur sumber:
gs://bucketA/alpha - Kecualikan awalan:
beta/ - Hasil: Tindakan ini akan mengecualikan
gs://bucketA/alpha/betadengan benar
Salah
- Jalur sumber:
gs://bucketA/alpha - Kecualikan awalan:
alpha/beta/ - Hasil: Tindakan ini salah menentukan filter untuk
gs://bucketA/alpha/alpha/beta
Menentukan awalan
Konsol Google Cloud
Untuk menentukan awalan penyertaan dan pengecualian menggunakan konsolGoogle Cloud , masukkan nilai saat membuat transfer baru atau saat memperbarui transfer yang ada.
gcloud CLI
Untuk menentukan awalan penyertaan dan pengecualian menggunakan gcloud CLI, teruskan flag --include-prefixes dan --exclude-prefixes ke perintah gcloud transfer jobs create atau perintah gcloud transfer jobs update:
gcloud transfer jobs create SOURCE DESTINATION \
--include-prefixes="path_1/,path_2/" --exclude-prefixes="path_1/subpath_2/"
Pisahkan beberapa awalan dengan koma, tanpa menyertakan spasi setelah koma.
Misalnya, --include-prefixes="foo,bar".
REST
Untuk menentukan awalan penyertaan dan pengecualian menggunakan REST API, gunakan kolom includePrefixes[] dan excludePrefixes[]:
{
"description": "Transfer with prefixes",
"status": "ENABLED",
"projectId": "PROJECT_ID",
"schedule": {
"scheduleStartDate": {
"day": 1,
"month": 1,
"year": 2015
},
"startTimeOfDay": {
"hours": 1,
"minutes": 1
}
},
"transferSpec": {
"gcsDataSource": {
"bucketName": "SOURCE_BUCKET"
},
"gcsDataSink": {
"bucketName": "DESTINATION_BUCKET"
},
"transferOptions": {
"deleteObjectsFromSourceAfterTransfer": true
},
"objectConditions": {
"includePrefixes": [
"path_1/",
"path_2/"
],
"excludePrefixes": [
"path_1/subpath_2/object_5"
]
}
}
}
Untuk mengetahui informasi selengkapnya, lihat referensi ObjectConditions.
Contoh objek dan jalur
Contoh berikut menggunakan daftar objek contoh ini:
xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8
Menggunakan awalan penyertaan
Untuk mentransfer hanya objek di bagian path_1/, gunakan awalan berikut:
path_1/
Hal ini mencakup objek di bagian path_1/. Objek berikut disertakan dalam
transfer:
xx://bucketname/object_1xx://bucketname/object_2xx://bucketname/path_1/object_3 xx://bucketname/path_1/subpath_1/object_4 xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Anda dapat menentukan beberapa jalur untuk disertakan. Misalnya, Anda dapat meneruskan hal berikut:
path_1/subpath_2/ path_2/subpath_3/
Dalam hal ini, transfer mencakup objek berikut:
xx://bucketname/object_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Pencocokan parsial didukung. Contoh:
path
Objek berikut akan ditransfer:
xx://bucketname/object_1xx://bucketname/object_2xx://bucketname/path_1/object_3 xx://bucketname/path_1/subpath_1/object_4 xx://bucketname/path_1/subpath_2/object_5 xx://bucketname/path_2/object_6 xx://bucketname/path_2/subpath_3/object_7 xx://bucketname/path_2/subpath_4/object_8
Saat Anda menggunakan awalan penyertaan, jalur yang tidak Anda sertakan secara khusus tidak akan ditransfer ke bucket tujuan Cloud Storage.
Mengecualikan awalan
Menggunakan awalan pengecualian saat membuat transfer akan menginstruksikan Storage Transfer Service untuk mengabaikan jalur yang tercantum untuk transfer.
Untuk mengecualikan objek di bagian path_1/, teruskan awalan berikut:
path_1/
Ini tidak termasuk objek di bawah path_1/. Dalam hal ini, objek berikut
disertakan dalam transfer:
xx://bucketname/object_1 xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6 xx://bucketname/path_2/subpath_3/object_7 xx://bucketname/path_2/subpath_4/object_8
Anda dapat menentukan beberapa jalur yang akan dikecualikan. Misalnya, Anda dapat meneruskan hal berikut:
path_1/subpath_2/
path_2/subpath_3/
Dalam hal ini, transfer mencakup objek berikut:
xx://bucketname/object_1 xx://bucketname/object_2 xx://bucketname/path_1/object_3 xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Menyertakan dan mengecualikan jalur secara bersamaan
Anda dapat menerapkan awalan pengecualian dan awalan penyertaan secara bersamaan, dalam hal ini awalan pengecualian membatasi apa yang disertakan oleh awalan penyertaan dalam transfer.
Saat menentukan kedua jenis awalan, setiap awalan pengecualian harus dimulai dengan jalur yang ditentukan dalam awalan penyertaan.
Misalnya, untuk menyertakan objek di bawah path_1/ dan mengecualikan objek di bawah
subpath_1/, teruskan hal berikut:
include: path_1/
exclude: path_1/subpath_1/
Dalam hal ini, transfer mencakup objek berikut:
xx://bucketname/object_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Untuk menyertakan semua objek di bagian path_1/ dan path_2/, kecuali item di
path_1/subpath_1/ atau path_2/subpath_3/, teruskan hal berikut:
include: path_1/
path_2/
exclude: path_1/subpath_1/
path_2/subpath_3/
Dalam hal ini, transfer mencakup objek berikut:
xx://bucketname/object_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5 xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Kesalahan umum yang harus dihindari
Berikut adalah contoh konfigurasi yang salah dan cara memperbaikinya.
Menyertakan jalur yang digunakan dalam awalan penyertaan lain
Awalan penyertaan tidak boleh berupa subdirektori dari awalan penyertaan lain.
Salah: Jalur awalan path_1/subpath_1 sudah tercakup oleh path_1/.
include: path_1/
path_1/subpath_1
Benar: Untuk memperbaikinya, hapus awalan yang redundan dan lebih spesifik.
include: path_1/
Awalan pengecualian tidak cocok dengan awalan penyertaan
Jika digunakan bersama, awalan pengecualian harus dimulai dengan salah satu awalan penyertaan.
Salah: Awalan subpath_1 tidak dimulai dengan path_1/ atau
path_2/.
include: path_1/
path_2/
exclude: subpath_1
Benar: Pastikan awalan pengecualian berisi jalur lengkap dari awalan penyertaan.
include: path_1/
path_2/
exclude: path_1/subpath_1/