סינון אובייקטים במקור לפי תחילית

במדריך הזה מוסבר איך להשתמש בקידומות להכללה ולהחרגה כדי לקבוע אילו קבצים יועברו.

סקירה כללית

‫Storage Transfer Service תומך בסינון נתונים ממקורות של Amazon S3, ‏ Microsoft Azure Blob Storage ו-Cloud Storage באמצעות קידומות. קידומת היא מחרוזת של תווים בתחילת נתיב שמציינת קבוצה של אובייקטים.

יש שלוש דרכים להשתמש במסנני קידומות:

• כולל קידומות: רק אובייקטים שתואמים לקידומות שצוינו מועברים.

• החרגת קידומות: אובייקטים שתואמים לקידומות שצוינו מושמטים מההעברה.

• גם וגם: אתם יכולים להשתמש בקידומות של החרגה ושל הכללה בו-זמנית כדי לקבל שליטה מדויקת יותר. כשמשתמשים בהם יחד, כל קידומת של החרגה חייבת להתחיל באחת מהקידומות של הכללה שצוינו.

אם לא מציינים קידומות, כל האובייקטים בקטגוריית המקור מועברים.

כללים

הכללים הבאים חלים על קידומות:

• ללא קווים נטויים בתחילת המחרוזת: אל תכללו קו נטוי בתחילת הקידומת. בנתיב s3://my-bucket/logs/2025/requests.gz, התחילית הנכונה היא logs/2025/requests.gz.

• התאמות חלקיות: התאמה חלקית היא הדרך שבה קידומות פועלות. לדוגמה, הקידומת path תואמת ל-path_1/ ול-path_2/.

• ללא תווים כלליים לחיפוש: לא אפשרי.

• ביחס לתיקיית המקור: אם מקור ההעברה כולל נתיב או תיקייה, הקידומות הן ביחס לנתיב או לתיקייה האלה. פרטים נוספים זמינים במאמר בנושא אינטראקציה עם נתיב או תיקייה של מקור.

• קידומות include נפרדות: כל קידומת include צריכה להגדיר חלק ייחודי במרחב השמות של האובייקט. אי אפשר להשתמש בתחילית include שכבר נכללת בתחילית include אחרת. לדוגמה, אי אפשר לציין גם את data/ וגם את data/reports/ כקידומות להכללה.

• החרגת תלות בקידומת: כשמשתמשים בקידומות של הכללה והחרגה ביחד, כל קידומת של החרגה חייבת להתחיל באחת מקידומות ההכללה שצוינו. לדוגמה, אם path היא קידומת של הכללה, קידומות תקפות של החרגה יכולות להיות path/b או pathway. הכלל הזה לא חל אם משתמשים רק בקידומות להחרגה.

• מקסימום 1,000 קידומות: משימת העברה אחת תומכת ב-1,000 קידומות לכל היותר. אפשר לפצל העברה לכמה משימות אם נדרשים קידומות נוספות.

מידע כללי נוסף על תחיליות זמין במאמר הצגת רשימה של מפתחות באופן היררכי באמצעות תחילית ותו מפריד במסמכי Amazon S3 או במאמר שיטה להצגת רשימה של אובייקטים ב-Cloud Storage.

אינטראקציה עם סוגים אחרים של מסננים

כשמשתמשים בכמה מסננים, Storage Transfer Service מחיל אותם בסדר הבא:

1. הוספת קידומות: מצמצמת את האובייקטים שצריך לקחת בחשבון.

2. תנאי אובייקט (מועד השינוי האחרון): מסנן את האובייקטים שתואמים לקידומת ההכללה. כדי שאובייקט ייכלל בתוצאה, הוא צריך להתאים למסנן של מועד השינוי האחרון.

3. החרגת קידומות: הסרת אובייקטים מהתוצאה.

אינטראקציה עם נתיב או תיקייה של מקור

מסנני הכללה והחרגה הם יחסי לכל נתיב או תיקייה שאתם מציינים למקור.

לדוגמה, אם המקור שלכם הוא 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

כדי לציין קידומות להכללה ולמעט באמצעות 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

כדי לציין קידומות שרוצים לכלול או להחריג באמצעות 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_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/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_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

האובייקטים הבאים מועברים:

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

כשמשתמשים בתחיליות של נתיבים שרוצים לכלול, נתיבים שלא נכללים באופן ספציפי לא מועברים לקטגוריית היעד ב-Cloud Storage.

החרגת תוספות לשם של מאפיין

כשמשתמשים בקידומות של אי הכללה כשיוצרים העברה, Storage Transfer Service מתעלם מהנתיבים שמופיעים ברשימה לצורך ההעברה.

כדי להחריג אובייקטים מתחת ל-path_1/, מעבירים את הקידומת הבאה:

path_1/

הפעולה הזו לא כוללת אובייקטים שנמצאים ב-path_1/. במקרה כזה, האובייקטים הבאים נכללים בהעברה:

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/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_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/ ולהחריג אובייקטים מתחת ל-subpath_1/, מעבירים את הפקודה הבאה:

include: path_1/
exclude: path_1/subpath_1/

במקרה הזה, ההעברה כוללת את האובייקטים הבאים:

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

טעויות נפוצות שכדאי להימנע מהן

ריכזנו כאן דוגמאות להגדרות שגויות והסבר איך לתקן אותן.

כולל נתיב שמשמש בתחילית אחרת של include

קידומת include לא יכולה להיות ספריית משנה של קידומת include אחרת.

שגוי: הנתיב עם הקידומת 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/