このガイドでは、包含接頭辞と除外接頭辞を使用して、転送するファイルを制御する方法について説明します。
概要
Storage Transfer Service を使用すると、接頭辞を使用して Amazon S3、Microsoft Azure Blob Storage、Cloud Storage のソースからデータをフィルタできます。プレフィックスは、パスの先頭にある文字列で、オブジェクトのセットを指定します。
接頭辞フィルタは次の 3 つの方法で使用できます。
接頭辞を含める: 指定された接頭辞に一致するオブジェクトのみが転送されます。
接頭辞を除外: 指定された接頭辞に一致するオブジェクトは転送から除外されます。
両方: 包含接頭辞と除外接頭辞を同時に使用して、より詳細な制御を行うことができます。一緒に使用する場合、すべての除外接頭辞は、指定された包含接頭辞のいずれかで始まる必要があります。
接頭辞を指定しないと、ソースバケット内のすべてのオブジェクトが転送されます。
ルール
接頭辞には次のルールが適用されます。
先頭のスラッシュなし: 接頭辞の先頭はスラッシュにしないでください。パス
s3://my-bucket/logs/2025/requests.gzの場合、正しい接頭辞はlogs/2025/requests.gzです。部分一致: 接頭辞は部分一致で機能します。たとえば、接頭辞
pathはpath_1/とpath_2/の両方に一致します。ワイルドカードなし: ワイルドカードはサポートされていません。
ソースフォルダを基準とする: 転送元が特定のフォルダの場合、接頭辞はそのフォルダを基準として評価されます。ソースが
gs://my-bucket/data/の場合、reportsの一致接頭辞はgs://my-bucket/data/reportsのすべてのファイルと一致します。個別の包含接頭辞: 各包含接頭辞は、オブジェクトの名前空間の一意の部分を定義する必要があります。別の包含接頭辞ですでにカバーされている包含接頭辞を使用することはできません。たとえば、
data/とdata/reports/の両方を包含接頭辞として指定することはできません。除外接頭辞の依存関係: 包含接頭辞と除外接頭辞を一緒に使用する場合、すべての除外接頭辞は、指定された包含接頭辞のいずれかで始まる必要があります。たとえば、
pathが包括接頭辞の場合、有効な除外接頭辞はpath/bまたはpathwayになります。除外接頭辞のみを使用している場合、このルールは適用されません。最大 1,000 個の接頭辞: 1 つの転送ジョブで最大 1,000 個の接頭辞をサポートします。追加の接頭辞が必要な場合は、転送を複数のジョブに分割できます。
接頭辞に関する一般的な情報については、Amazon S3 ドキュメントのプレフィックスと区切り記号によるキーの階層的なリストまたは Cloud Storage のオブジェクト リストの表示方法をご覧ください。
接頭辞を指定する方法
Cloud コンソール
Cloud コンソールを使用して包含接頭辞と除外接頭辞を指定するには、新しい転送の作成時または既存の転送の更新時に値を入力します。
gcloud CLI
gcloud CLI を使用して包含接頭辞と除外接頭辞を指定するには、--include-prefixes フラグと --exclude-prefixes フラグを gcloud transfer jobs create コマンドまたは gcloud transfer jobs update コマンドに渡します。
gcloud transfer jobs create SOURCE DESTINATION \
--include-prefixes="path_1/,path_2/" --exclude-prefixes="path_1/subpath_2/"
複数の接頭辞を指定する場合は、接頭辞をカンマで区切ります。カンマの後にスペースを入れないでください。例: --include-prefixes="foo,bar"
REST
REST API を使用して包含接頭辞と除外接頭辞を指定するには、includePrefixes[] フィールドと excludePrefixes[] フィールドを使用します。
{
"description": "YOUR DESCRIPTION",
"status": "ENABLED",
"projectId": "PROJECT_ID",
"schedule": {
"scheduleStartDate": {
"day": 1,
"month": 1,
"year": 2015
},
"startTimeOfDay": {
"hours": 1,
"minutes": 1
}
},
"transferSpec": {
"gcsDataSource": {
"bucketName": "GCS_SOURCE_NAME"
},
"gcsDataSink": {
"bucketName": "GCS_SINK_NAME"
},
"transferOptions": {
"deleteObjectsFromSourceAfterTransfer": true
},
"objectConditions": {
"includePrefixes": [
"path_1/",
"path_2/"
],
"excludePrefixes": [
"path_1/subpath_2/object_5"
]
}
}
}
詳細については、ObjectConditions リファレンスをご覧ください。
オブジェクトとパスの例
次の例では、このオブジェクトのサンプル リストを使用します。
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
包含接頭辞を使用する
path_1/ 下にあるオブジェクトのみを転送するには、次の接頭辞を使用します。
path_1/
これには、path_1/ の下のオブジェクトが含まれます。次のオブジェクトが転送に含められます。
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
含めるパスは複数指定できます。たとえば、次のものを渡すことができます。
path_1/subpath_2/ path_1/subpath_3/
この場合、次のオブジェクトが転送に含められます。
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
部分一致はサポートされます。次に例を示します。
path
次のオブジェクトが転送されます。
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
接頭辞を使用する場合、明示的に含めていないパスは、Cloud Storage 転送先バケットに転送されません。
除外接頭辞
転送の作成時に除外接頭辞を使用して、一覧表示されたパスを転送対象から除外するように、Storage Transfer Service に指示します。
path_1/ 下にあるオブジェクトを除外するには、次の接頭辞を渡します。
path_1/
これにより、path_1/ の下にあるオブジェクトが除外されます。この場合、次のオブジェクトが転送に含められます。
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
除外する複数のパスを指定できます。たとえば、次のものを渡すことができます。
path_1/subpath_2/
path_2/subpath_3/
この場合、次のオブジェクトが転送に含められます。
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
含めるパスと除外するパスを同時に指定する
除外接頭辞と包含接頭辞は一緒に適用できます。その場合、除外接頭辞により、転送の包含接頭辞の上限が決まります。
両方のタイプの接頭辞を指定する場合、各除外接頭辞は、包含接頭辞で指定されたパスで始まる必要があります。
たとえば、path_1/ 下にあるオブジェクトを含めて、subpath_1/ 下にあるオブジェクトを除外するには、次を渡します。
include: path_1/
exclude: path_1/subpath_1/
この場合、次のオブジェクトが転送に含められます。
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
path_1/subpath_1/ または path_2/subpath_3/ のアイテムを除いて path_1/ と path_2/ の下にあるすべてのオブジェクトを含めるには、次を渡します。
include: path_1/
path_2/
exclude: path_1/subpath_1/
path_2/subpath_3/
この場合、次のオブジェクトが転送に含められます。
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
避けるべきよくある間違い
構成が正しくない例と、その修正方法を次に示します。
別の包含接頭辞で使用されるパスを含める
包含接頭辞は別の包含接頭辞のサブディレクトリにすることはできません。
誤り: 接頭辞 path_1/subpath_1 はすでに path_1/ でカバーされています。
include: path_1/
path_1/subpath_1
正しい: これを修正するには、冗長でより具体的な接頭辞を削除します。
include: path_1/
除外接頭辞が包含接頭辞と一致しない
一緒に使用する場合、除外接頭辞は包含接頭辞のいずれかで始まる必要があります。
不正: subpath_1 接頭辞が path_1/ または path_2/ で始まっていません。
include: path_1/
path_2/
exclude: subpath_1
正しい: 除外接頭辞に包含接頭辞のフルパスが含まれていることを確認します。
include: path_1/
path_2/
exclude: path_1/subpath_1/