במדריך הזה מוסבר איך להשתמש בתחיליות להכללה ולהחרגה כדי לקבוע אילו קבצים יועברו.
סקירה כללית
ב-Storage Transfer Service אפשר לסנן נתונים ממקורות של Amazon S3, Microsoft Azure Blob Storage ו-Cloud Storage באמצעות קידומות. קידומת היא מחרוזת של תווים בתחילת הנתיב שמציינת קבוצה של אובייקטים.
אפשר להשתמש במסנני קידומת בשלוש דרכים:
Include prefixes: רק אובייקטים שתואמים לקידומות שצוינו מועברים.
החרגת קידומות: אובייקטים שתואמים לקידומות שצוינו מושמטים מההעברה.
שניהם ביחד: אתם יכולים להשתמש בתחיליות להכללה ולהחרגה בו-זמנית כדי לקבל שליטה מפורטת יותר. כשמשתמשים בשתי המדיניות, כל קידומת להחרגה חייבת להתחיל באחת מהקידומות להכללה שצוינו.
אם לא מציינים תחיליות, כל האובייקטים בקטגוריית המקור מועברים.
אפשר לשלב מסנני קידומות עם תבניות glob, מסננים של מועד השינוי האחרון ומסננים של סוגי אחסון ב-S3.
כללים
הכללים הבאים חלים על קידומות:
בלי קווים נטויים בתחילת הקידומת: אל תכללו קו נטוי בתחילת הקידומת. בנתיב
s3://my-bucket/logs/2025/requests.gz, התחילית הנכונה היאlogs/2025/requests.gz.התאמות חלקיות: קידומות פועלות לפי התאמה חלקית. לדוגמה, הקידומת
pathתואמת גם ל-path_1/וגם ל-path_2/.אין תווים כלליים לחיפוש: אין תמיכה בתווים כלליים לחיפוש.
ביחס לתיקיית המקור: אם מקור ההעברה כולל נתיב או תיקייה, הקידומות הן ביחס לנתיב או לתיקייה האלה. לפרטים נוספים, ראו אינטראקציה עם נתיב המקור או התיקייה.
קידומות נפרדות: כל קידומת הכללה צריכה להגדיר חלק ייחודי של מרחב השמות של האובייקט. אי אפשר להשתמש בקידומת הכללה שכבר נכללת בקידומת הכללה אחרת. לדוגמה, אי אפשר לציין גם את
data/וגם אתdata/reports/כתחיליות להכללה. אותו כלל חל גם על קידומות להחרגה.תלות בקידומת להחרגה: כשמשתמשים בקידומות להכללה ולהחרגה ביחד, כל קידומת להחרגה חייבת להתחיל באחת מהקידומות להכללה שצוינו. לדוגמה, אם
pathהיא תחילת מחרוזת להכללה, תחילת מחרוזת להחרגה יכולה להיותpath/bאוpathway. הכלל הזה לא חל אם אתם משתמשים רק בקידומות להחרגה.עד 1,000 תחיליות מכל סוג: משימת העברה אחת תומכת בעד 1,000 תחיליות להכללה ועד 1,000 תחיליות להחרגה. אם נדרשות תחיליות נוספות, אפשר לפצל העברה לכמה משימות.
למידע כללי נוסף על תחיליות, קראו את המאמר Listing Keys Hierarchically Using a Prefix and Delimiter במסמכי התיעוד של Amazon S3 או את המאמר Objects list method של Cloud Storage.
אינטראקציה עם סוגי מסננים אחרים
כשמשתמשים בכמה מסננים, Storage Transfer Service מחיל אותם בסדר הבא:
- Include prefixes: מצמצם את האובייקטים שצריך להביא בחשבון.
- תנאי אובייקט (תבנית glob, זמן השינוי האחרון וסוג האחסון ב-S3): מסננים את האובייקטים שתואמים לתחילית ההכללה. כדי שאובייקט ייכלל בהעברה, הוא צריך לעמוד בכל התנאים שצוינו.
- Exclude prefixes: הסרת אובייקטים מהתוצאה.
מידע נוסף על סינון באמצעות תבניות glob, זמן השינוי האחרון וסוג האחסון ב-S3.
אינטראקציה עם נתיב או תיקייה של מקור
מסנני ההכללה וההחרגה הם יחסיים לכל נתיב או תיקייה שאתם מציינים למקור.
לדוגמה, אם המקור הוא gs://bucketA/alpha ואתם רוצים לציין מסנן ל-gs://bucketA/alpha/beta:
נכון
- נתיב המקור:
gs://bucketA/alpha - קידומת להחרגה:
beta/ - תוצאה: המערכת מחריגה את
gs://bucketA/alpha/betaבצורה נכונה
שגוי
- נתיב המקור:
gs://bucketA/alpha - קידומת להחרגה:
alpha/beta/ - תוצאה: זה מגדיר באופן שגוי מסנן עבור
gs://bucketA/alpha/alpha/beta
צריך לציין תחיליות
מסוף Google Cloud
כדי לציין תחיליות להכללה ולהחרגה באמצעות מסוףGoogle Cloud , מזינים את הערכים כשיוצרים העברה חדשה או כשמעדכנים העברה קיימת.
CLI של gcloud
כדי לציין תחיליות להכללה ולהחרגה באמצעות ה-CLI של gcloud, מעבירים את הדגלים --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
כדי לציין תחיליות להכללה ולהחרגה באמצעות ה-API בארכיטקטורת REST, משתמשים בשדות includePrefixes[] ו-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"
]
}
}
}
מידע נוסף זמין במאמר העזרה בנושא 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_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_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/ וב-path_2/, חוץ מהפריטים ב-path_1/subpath_1/ או ב-path_2/subpath_3/, מעבירים את הפרמטרים הבאים:
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/