FTP

מחבר ה-FTP מאפשר לכם להתחבר לשרת FTP ולבצע פעולות של העברת קבצים.

לפני שמתחילים

לפני שמשתמשים במחבר FTP, צריך לבצע את המשימות הבאות:

  • בפרויקט שלכם ב-Google Cloud:
    • מוודאים שהגדרתם חיבור לרשת. מידע על תבניות רשת זמין במאמר קישוריות לרשת.
    • נותנים למשתמש שמגדיר את המחבר את תפקיד ה-IAM‏ roles/connectors.admin.
    • מקצים לחשבון השירות שרוצים להשתמש בו עבור המחבר את תפקידי ה-IAM הבאים:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      חשבון שירות הוא סוג מיוחד של חשבון Google שמייצג משתמש לא אנושי, שצריך לאמת ולאשר כדי לתת לו גישה לנתונים ב-Google APIs. אם אין לכם חשבון שירות, אתם צריכים ליצור חשבון שירות. המחבר וחשבון השירות צריכים להיות שייכים לאותו פרויקט. מידע נוסף זמין במאמר בנושא יצירת חשבון שירות.

    • מפעילים את השירותים הבאים:
      • ‫secretmanager.googleapis.com (Secret Manager API)
      • ‫connectors.googleapis.com (Connectors API)

      במאמר הפעלת שירותים מוסבר איך להפעיל שירותים.

    אם השירותים או ההרשאות האלה לא הופעלו בפרויקט שלכם בעבר, תתבקשו להפעיל אותם כשאתם מגדירים את המחבר.

הגדרת המחבר

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

  1. במסוף Cloud, עוברים לדף Integration Connectors > Connections ובוחרים או יוצרים פרויקט בענן.

    כניסה לדף Connections

  2. לוחצים על + יצירת חיבור חדש כדי לפתוח את הדף יצירת חיבור.
  3. בקטע מיקום, בוחרים את המיקום של החיבור.
    1. אזור: בוחרים מיקום מהרשימה הנפתחת.

      רשימה של כל האזורים הנתמכים מופיעה במאמר מיקומים.

    2. לוחצים על הבא.
  4. בקטע פרטי החיבור, ממלאים את הפרטים הבאים:
    1. מחבר: בוחרים באפשרות FTP מהרשימה הנפתחת של המחברים הזמינים.
    2. גרסת כלי החיבור: בוחרים את גרסת כלי החיבור מהרשימה הנפתחת של הגרסאות הזמינות.
    3. בשדה Connection Name (שם החיבור), מזינים שם למופע החיבור.

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

      • שמות החיבורים יכולים לכלול אותיות, מספרים או מקפים.
      • האותיות צריכות להיות קטנות.
      • שמות החיבורים צריכים להתחיל באות ולהסתיים באות או במספר.
      • שמות החיבורים לא יכולים לכלול יותר מ-49 תווים.
    4. אופציונלי: מזינים תיאור למופע החיבור.
    5. אופציונלי: מפעילים את Cloud Logging ואז בוחרים רמת יומן. כברירת מחדל, רמת היומן מוגדרת כ-Error.
    6. חשבון שירות: בוחרים חשבון שירות שיש לו את התפקידים הנדרשים.
    7. אופציונלי: מגדירים את ההגדרות של צומת החיבור:

      • מספר מינימלי של צמתים: מזינים את המספר המינימלי של צמתי חיבור.
      • מספר הצמתים המקסימלי: מזינים את מספר צמתי החיבור המקסימלי.

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

    8. עומק אחזור הקבצים: מציינים את רמת העומק של התיקיות שרוצים לשלוף מהטבלה Root.
    9. פסיבי: קובע אם לכוון את השרת למצב פסיבי. מומלץ אם נמצאים מאחורי חומת אש.
    10. נתיב מרוחק: הנתיב הנוכחי בשרת ה-FTP.
    11. מצב SSL: מנגנון האימות שישמש להתחברות לשרת ה-FTP.
    12. עומק הטבלה: רמת העומק שבה תיקיות המשנה יוצגו כתצוגות.
    13. שימוש ב-MLSD: שימוש בכרטיסי מוצר לעיבוד מכונה. משמש רק לשרתי FTP.
    14. אופציונלי: לוחצים על + הוספת תווית כדי להוסיף תווית לקישור בצורה של צמד מפתח/ערך.
    15. לוחצים על הבא.
  5. בקטע יעדים, מזינים את הפרטים של המארח המרוחק (מערכת העורף) שאליו רוצים להתחבר.
    1. סוג היעד: בוחרים סוג יעד.
      • כדי לציין את שם המארח או את כתובת ה-IP של היעד, בוחרים באפשרות כתובת המארח ומזינים את הכתובת בשדה מארח 1.
      • כדי ליצור חיבור פרטי, בוחרים באפשרות Endpoint attachment (צירוף נקודת קצה). ברשימה Endpoint Attachment, בוחרים את קובץ ה-Endpoint Attachment שנוצר עבור מערכת ה-Backend.

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

      כדי להזין יעדים נוספים, לוחצים על +הוספת יעד.

    2. לוחצים על הבא.
  6. בקטע אימות, מזינים את פרטי האימות.
    1. בוחרים סוג אימות ומזינים את הפרטים הרלוונטיים.

      חיבור ה-FTP תומך בסוגי האימות הבאים:

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

    3. לוחצים על הבא.
  7. בדיקה: בודקים את פרטי החיבור והאימות.
  8. לוחצים על יצירה.

הגדרת אימות

מזינים את הפרטים בהתאם לאימות שבו רוצים להשתמש.

  • שם משתמש וסיסמה
    • שם משתמש: שם המשתמש ב-FTP שבו רוצים להשתמש לחיבור.
    • סיסמה: סוד ב-Secret Manager שמכיל את הסיסמה שמשויכת לשם המשתמש ב-FTP.

ישויות, פעולות ופעולות

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

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

    עם זאת, יכול להיות שמחבר לא תומך בישויות או שאין לו ישויות, ובמקרה כזה הרשימה Entities תהיה ריקה.

  • פעולה: פעולה היא הפעילות שאפשר לבצע בישות. אפשר לבצע כל אחת מהפעולות הבאות בישות:

    בחירה של ישות מתוך הרשימה הזמינה יוצרת רשימה של פעולות שזמינות לישות. תיאור מפורט של הפעולות זמין במאמר פעולות על ישויות של משימת המחברים. עם זאת, אם מחבר לא תומך באף אחת מהפעולות על ישויות, הפעולות הלא נתמכות האלה לא יופיעו ברשימה Operations.

  • פעולה: פעולה היא פונקציה מסוג first class שזמינה לשילוב דרך ממשק המחבר. פעולה מאפשרת לבצע שינויים בישות אחת או בכמה ישויות, והיא משתנה ממתחם למתחם. בדרך כלל, לפעולה יהיו כמה פרמטרים של קלט ופרמטר של פלט. עם זאת, יכול להיות שמחבר לא תומך באף פעולה, ובמקרה כזה הרשימה Actions תהיה ריקה.

מגבלות המערכת

מחבר ה-FTP יכול לעבד טרנזקציה אחת בשנייה, לכל צומת, ומגביל את כל הטרנזקציות שחורגות מהמגבלה הזו. כברירת מחדל, Integration Connectors מקצה 2 צמתים (לזמינות טובה יותר) לחיבור.

מידע על המגבלות שחלות על Integration Connectors זמין במאמר מגבלות.

פעולות

בקטע הזה מפורטות חלק מהפעולות שהמחבר תומך בהן. כדי להבין איך להגדיר את הפעולות, אפשר לעיין בדוגמאות לפעולות.

פעולת העלאה

בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה Upload.

שם הפרמטר סוג נתונים חובה תיאור
תוכן String לא תוכן להעלאה כקובץ.
ContentBytes String לא תוכן בבייט (כמחרוזת Base64) להעלאה כקובץ. משתמשים באפשרות הזו כדי להעלות נתונים בינאריים.
HasBytes בוליאני לא מציין אם התוכן צריך להיות מועלה כבייטים. ערך ברירת המחדל הוא false.
RemoteFile String כן שם הקובץ במארח המרוחק.
החלפה בוליאני לא מציין אם צריך להחליף את הקובץ המרוחק. ערך ברירת המחדל הוא false.

דוגמאות להגדרת הפעולה Upload מופיעות במאמר דוגמאות.

פעולת הורדה

בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה Download.

שם הפרמטר סוג נתונים חובה תיאור
RemoteFile String כן שם הקובץ במארח המרוחק.
HasBytes בוליאני לא מציין אם התוכן צריך להיות מורד כבייטים. ערך ברירת המחדל הוא false.

דוגמאות להגדרת הפעולה Download מופיעות במאמר דוגמאות.

פעולת MoveFile

בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה MoveFile.

שם הפרמטר סוג נתונים חובה תיאור
RemoteFile String כן הנתיב של הקובץ המרוחק שרוצים להעביר.
DestinationPath String כן הנתיב החדש שאליו רוצים להעביר את הקובץ.

דוגמאות להגדרת הפעולה MoveFile מופיעות במאמר דוגמאות.

פעולה RenameFile

בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה RenameFile.

שם הפרמטר סוג נתונים חובה תיאור
RemoteFile String כן הנתיב והשם של הקובץ המרוחק שרוצים לשנות.
NewFileName String כן השם החדש של הקובץ המרוחק.

דוגמאות להגדרת הפעולה RenameFile מופיעות במאמר דוגמאות.

דוגמאות

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

  • רשימה של כל הקבצים בספריית הבסיס
  • הצגת רשימת קבצים שתואמים לתבנית בספרייה
  • העברת קובץ
  • שינוי שם של קובץ
  • איך מוחקים קובץ
  • העלאה של קובץ טקסט ASCII
  • העלאת קובץ בינארי
  • הורדת קובץ טקסט בפורמט ASCII
  • הורדת קובץ בינארי

בטבלה הבאה מפורטים תרחישים לדוגמה וההגדרות המתאימות להם במשימה Connectors:

משימה פקודה לדוגמה הגדרות אישיות
רשימה של כל הקבצים בספריית הבסיס ls /
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים את ישות Root ואז בוחרים את פעולת List.
  3. לוחצים על סיום.
הצגת רשימת קבצים .csv בספרייה ls /tmp/*.csv
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים את ספריית הבסיס (/tmp) מהרשימה Entity.
  3. בוחרים את הפעולה List ולוחצים על סיום.
  4. הגדרת סעיף המסנן. כדי להגדיר את הסעיף, בקטע Task Input (קלט המשימה) של המשימה Connectors (מחברים), לוחצים על filterClause (סעיף סינון) ואז מזינים FilePath LIKE '/tmp/%.csv' בשדה Default Value (ערך ברירת מחדל).
העברת קובץ mv /tmp/dir_A/hello_world.txt /dir_B/dir_C/
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
  2. בוחרים את הפעולה MoveFile ולוחצים על סיום.
  3. בקטע Task Input (קלט משימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ואז מזינים ערך דומה לערך הבא בשדה Default Value:
    {
    "RemoteFile": "/tmp/dir_A/hello_world.txt",
    "DestinationPath": "/dir_B/dir_C/"
    }

בדוגמה הזו, הקובץ /tmp/dir_A/hello_world.txt מועבר לספרייה /dir_B/dir_C/. הפעלת הדוגמה הזו מחזירה תגובה דומה לזו שמופיעה במשתנה הפלט connectorOutputPayload של משימת המחבר:

[{
"Success":"true"
}]
שינוי שם של קובץ mv /tmp/hello_world.txt /tmp/hello_world_new.txt
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
  2. בוחרים את הפעולה RenameFile ולוחצים על סיום.
  3. בקטע Task Input (קלט משימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ואז מזינים ערך דומה לערך הבא בשדה Default Value:
    {
    "RemoteFile": "/tmp/hello_world.txt",
    "NewFilename": "hello_world_new.txt"
    }

בדוגמה הזו, שם הקובץ hello_world.txt משתנה ל-hello_world_new.txt. הפעלת הדוגמה הזו מחזירה תגובה דומה לזו שמופיעה במשתנה הפלט connectorOutputPayload של משימת המחבר:

[{
"Success":"true"
}]
איך מוחקים קובץ rm /tmp/myfile.csv
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. ברשימה Entity, בוחרים את ספריית הבסיס שכוללת את הקובץ שרוצים להעביר.
  3. בוחרים את הפעולה Delete ולוחצים על סיום.
  4. מגדירים את מזהה הישות לנתיב המלא של הקובץ. כדי להגדיר את מזהה הישות, בקטע Task Input (קלט משימה) של המשימה Connectors (מחברים), לוחצים על entityId (מזהה ישות) ומזינים את הערך /tmp/myfile.csv בשדה Default Value (ערך ברירת מחדל).

    לחלופין, במקום לציין את entityId, אפשר גם להגדיר את filterClause לערך FilePath LIKE '/tmp/myfile.csv'.

העלאה של קובץ טקסט ASCII put file_1.txt /tmp/file_1.txt
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
  2. בוחרים את הפעולה Upload ולוחצים על סיום.
  3. בקטע Task Input (קלט של משימה) במשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value:
    {
      "Content": "This is a sample text!\r\n",
      "RemoteFile": "/tmp/file_1.txt",
      "Overwrite": true
    }
  4. בדוגמה הזו נוצר הקובץ file_1.txt עם התוכן This is a sample text! בספרייה /tmp של שרת ה-FTP. כל קובץ קיים עם אותו שם יוחלף כי ערך המאפיין Overwrite הוא true.

    הגדרת המאפיין Overwrite היא אופציונלית. ערך ברירת המחדל הוא false.

העלאת קובץ בינארי put image_1.png /tmp/image_1.png כדי להעלות תוכן בינארי, קודם צריך לקודד את התוכן בפורמט Base64. אתם יכולים לבחור כלי לפי בחירתכם כדי לקודד את התוכן. השלבים לקידוד התוכן לא נכללים במסמך הזה. אחרי שיש לכם את התוכן כמחרוזת Base64, מבצעים את השלבים הבאים:
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
  2. בוחרים את הפעולה Upload ולוחצים על סיום.
  3. בקטע Task Input (קלט של משימה) במשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value:
    {
      "ContentBytes": "SGVsbG8gd29ybGQ=",
      "RemoteFile": "/tmp/image_1.png",
      "Overwrite": true,
      "HasBytes": true
    }
  4. בדוגמה הזו נוצר הקובץ image_1.png עם התוכן שצוין בשדה ContentBytes. הקובץ נוצר בספרייה /tmp בשרת ה-FTP. כל קובץ קיים עם אותו שם יוחלף כי ערך המאפיין Overwrite הוא true.

    הגדרת המאפיין Overwrite היא אופציונלית. ערך ברירת המחדל הוא false.

הורדת קובץ טקסט בפורמט ASCII get /tmp/myfile.txt
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
  2. בוחרים את הפעולה Download ולוחצים על סיום.
  3. בקטע Task Output (פלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value:
    {
    "RemoteFile": "/tmp/myfile.txt"
    }

התוכן של הקובץ שהורד זמין כמחרוזת בשדה Content של פרמטר התגובה connectorOutputPayload של משימת המחבר.

הורדת קובץ בינארי get /tmp/myfile.png
  1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
  2. בוחרים את הפעולה Download ולוחצים על סיום.
  3. בקטע Task Output (פלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value:
    {
    "RemoteFile": "/tmp/myfile.png",
    "HasBytes" : true
    }

תוכן הקובץ שהורד זמין כמחרוזת בקידוד Base64 בשדה ContentBytes של פרמטר התגובה connectorOutputPayload של משימת המחבר.

סכימת JSON למטען ייעודי (payload)

לכל אובייקט ישות בחיבור FTP יש סכימת JSON מוגדרת מראש. הבנה טובה של הסכימה מאפשרת לכם להגדיר בקלות את ערכי מטען הייעודי (payload) של הקלט או הפלט. אובייקטי הישות בחיבור FTP משתמשים בסכימת ה-JSON הבאה:

  {
    "type": "object",
    "properties": {
      "FilePath": {
        "type": "string",
        "readOnly": false
      },
      "Filename": {
        "type": [
          "string",
          "null"
        ],
        "readOnly": false,
        "description": "The name of the file or directory."
      },
      "FileSize": {
        "type": [
          "number",
          "null"
        ],
        "readOnly": false,
        "description": "The size of the file."
      },
      "LastModified": {
        "type": [
          "string",
          "null"
        ],
        "readOnly": false
      },
      "IsDirectory": {
        "type": [
          "boolean",
          "null"
        ],
        "readOnly": false
      },
      "Permissions": {
        "type": [
          "string",
          "null"
        ],
        "readOnly": false
      },
      "Owner": {
        "type": [
          "string",
          "null"
        ],
        "readOnly": false
      },
      "OwnerId": {
        "type": [
          "string",
          "null"
        ],
        "readOnly": false
      },
      "Group": {
        "type": [
          "string",
          "null"
        ],
        "readOnly": false
      },
      "GroupId": {
        "type": [
          "string",
          "null"
        ],
        "readOnly": false
      }
    }
  }

הגדרה דינמית של filterClause

בפעולות List,‏ Update ו-Delete, אפשר להגדיר את הערך של משתנה הקלט filterClasue באופן דינמי בזמן הריצה באמצעות המשימה Data Mapping בשילוב. לדוגמה, יכול להיות שתרצו לשלוח את הערך של משפט הסינון כשמפעילים את הטריגר של ה-API באינטגרציה. בתמונה הבאה מוצגת דוגמה למיפוי של המשתנה filterClause בכלי למיפוי נתונים במשימה 'מיפוי נתונים': הגדרת פסקה של מסנן בכלי לעריכת מיפוי הנתונים

יצירת חיבורים באמצעות Terraform

אפשר להשתמש במשאב של Terraform כדי ליצור חיבור חדש.

כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.

כדי לראות תבנית לדוגמה של Terraform ליצירת חיבור, אפשר לעיין בתבנית לדוגמה.

כשיוצרים את החיבור הזה באמצעות Terraform, צריך להגדיר את המשתנים הבאים בקובץ ההגדרות של Terraform:

שם הפרמטר סוג נתונים חובה תיאור
file_retrieval_depth מחרוזת לא נכון מציינים את רמת העומק של התיקיות שרוצים לשלוף מהטבלה Root.
פסיבי בוליאני לא נכון ההגדרה קובעת אם השרת יופעל במצב פסיבי. מומלץ אם נמצאים מאחורי חומת אש.
remote_path מחרוזת לא נכון הנתיב הנוכחי בשרת ה-FTP.
table_depth מספר שלם לא נכון רמת העומק שבה תיקיות משנה מוצגות כתצוגות.
use_mlsd בוליאני לא נכון שימוש בכרטיסי מוצר לעיבוד על ידי מכונה. משמש רק לשרתי FTP.

שימוש בחיבור FTP בשילוב

אחרי שיוצרים את החיבור, הוא זמין גם ב-Apigee Integration וגם ב-Application Integration. אפשר להשתמש בחיבור בשילוב באמצעות המשימה Connectors.

  • כדי להבין איך ליצור ולהשתמש במשימה Connectors ב-Apigee Integration, אפשר לעיין במאמר משימת Connectors.
  • מידע על יצירה ושימוש במשימת מחברים ב-Application Integration זמין במאמר משימת מחברים.

קבלת עזרה מקהילת Google Cloud

אתם יכולים לפרסם את השאלות שלכם ולדון במחבר הזה בקהילת Google Cloud בפורומים של Cloud.

המאמרים הבאים