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

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

סקירה כללית

ב-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 מחיל אותם בסדר הבא:

  1. Include prefixes: מצמצם את האובייקטים שצריך להביא בחשבון.
  2. תנאי אובייקט (תבנית glob, זמן השינוי האחרון וסוג האחסון ב-S3): מסננים את האובייקטים שתואמים לתחילית ההכללה. כדי שאובייקט ייכלל בהעברה, הוא צריך לעמוד בכל התנאים שצוינו.
  3. 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_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

טעויות נפוצות שחשוב להימנע מהן

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

כולל נתיב שנעשה בו שימוש בקידומת הכללה אחרת

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

לא נכון: הקידומת 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/