SFTP

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

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

בפרויקט Google Cloud, מבצעים את המשימות הבאות:

• מוודאים שהגדרתם חיבור לרשת. מידע נוסף זמין במאמר קישוריות לרשת.
• נותנים למשתמש שמגדיר את המחבר את תפקיד ה-IAM‏ roles/connectors.admin.
• מקצים את תפקידי ה-IAM‏ roles/secretmanager.viewer ו-roles/secretmanager.secretAccessor לחשבון השירות שבו רוצים להשתמש עבור המחבר. אם אין לכם חשבון שירות, אתם צריכים ליצור חשבון שירות. המחבר וחשבון השירות צריכים להיות שייכים לאותו פרויקט.
• מפעילים את secretmanager.googleapis.com (Secret Manager API) ואת connectors.googleapis.com (Connectors API). מידע נוסף זמין במאמר בנושא הפעלת שירותים.

יצירת חיבור SFTP

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

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

   כניסה לדף Connections

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

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

4. בקטע פרטי החיבור, ממלאים את הפרטים הבאים:
   1. בשדה Connector, בוחרים באפשרות SFTP.
   2. בשדה גרסת המחבר, בוחרים את הגרסה הרצויה.
   3. בשדה שם החיבור, מזינים שם למופע החיבור. שם החיבור יכול להכיל אותיות קטנות, מספרים או מקפים. השם חייב להתחיל באות ולהסתיים באות או במספר, והוא לא יכול להיות ארוך מ-49 תווים.
   4. אופציונלי: מזינים תיאור למופע החיבור.
   5. אופציונלי: מפעילים את Cloud Logging ואז בוחרים רמת יומן. כברירת מחדל, רמת היומן מוגדרת כ-Error.
   6. בשדה Service Account, בוחרים חשבון עם התפקידים הנדרשים.
   7. (אופציונלי) מגדירים את ההגדרות של צומת החיבור.
   • מספר מינימלי של צמתים: מזינים את המספר המינימלי של צמתי חיבור.
   • מספר הצמתים המקסימלי: מזינים את מספר צמתי החיבור המקסימלי.

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

   הערה: אפשר להתאים אישית את הערכים של צומת החיבור רק אם אתם לקוחות עם תשלום לפי שימוש.
   8. (אופציונלי) בשדה נתיב מרוחק, מזינים את נתיב התיקייה בשרת ה-SFTP כדי לבצע את פעולות הישות, כמו List, Create, Update או Delete.

   אם אתם ניגשים לישויות (קבצים או תיקיות) בתיקיית הבסיס או בתיקיות הצאצא המיידיות של תיקיית הבסיס, אתם לא צריכים להגדיר ערך בשדה הזה. עם זאת, אם רוצים לגשת לישויות מוטמעות שנמצאות בעומק של 2 רמות או יותר מתיקיית הבסיס, צריך להגדיר את הערך של השדה הזה לנתיב הבסיס של התיקייה שמכילה את הישויות שרוצים לגשת אליהן. לדוגמה, אם רוצים לגשת לקובץ /folder_A/folder_B/folder_C/test.png, צריך להגדיר את הנתיב המרוחק ל-/folder_A/folder_B/folder_C.

   9. אופציונלי: לוחצים על + הוספת תווית כדי להוסיף תווית לקישור בצורה של צמד מפתח/ערך.
   10. לוחצים על הבא.
5. בקטע יעדים, מזינים את הפרטים של המארח המרוחק (מערכת העורף) שאליו רוצים להתחבר ולוחצים על הבא.

בשדה סוג היעד, בוחרים את הסוג הרצוי:

• כדי לציין את שם המארח או את כתובת ה-IP של היעד, בוחרים באפשרות כתובת המארח ומזינים את הכתובת בשדה מארח 1.
• כדי ליצור חיבור פרטי, בוחרים באפשרות Endpoint attachment. ברשימה Endpoint Attachment, בוחרים את קובץ נקודת הקצה שנוצר למערכת העורפית.
הערה: מידע על יצירת צירוף של נקודת קצה זמין במאמר קישוריות לרשת פרטית. אחרי שיוצרים את ההצמדה של נקודת הקצה, היא מופיעה ברשימה Endpoint Attachment.

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

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

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

   • שם משתמש וסיסמה
   • SSH_PUBLIC_KEY

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

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

הגדרת אימות

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

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

• SSH_PUBLIC_KEY
  • שם משתמש: שם המשתמש בחשבון SFTP שמשמש לאימות.
  • מפתח SSH פרטי: מפתח פרטי לאימות SSH.
  • סיסמה של מפתח פרטי של SSH: ביטוי גישה או סיסמה להגנה על המפתח הפרטי, אם יש כאלה.
  • סוג מפתח SSH פרטי: הפורמט של המפתח הפרטי.

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

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

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

פעולות

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

הערה: התוצאות של כל הפעולות יהיו זמינות כתגובת JSON בפרמטר התגובה של משימת Connectors connectorOutputPayload אחרי שמריצים את השילוב.

פעולת העלאה

בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה 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 /	בתיבת הדו-שיח Configure connector task, לוחצים על Entities. בוחרים את ישות Root ואז בוחרים את פעולת List. לוחצים על סיום.
הצגת רשימת קבצים .csv בספרייה	ls /tmp/*.csv	בתיבת הדו-שיח Configure connector task, לוחצים על Entities. בוחרים את ספריית הבסיס (/tmp) מהרשימה Entity. בוחרים את הפעולה List ולוחצים על סיום. מגדירים את סעיף הסינון. כדי להגדיר את הסעיף, בקטע Task Input (קלט משימה) של המשימה Connectors (מחברים), לוחצים על filterClause (סעיף סינון) ואז מזינים FilePath LIKE '/tmp/%.csv' בשדה Default Value (ערך ברירת מחדל). הערה: הערך של תבנית הקובץ במשפט הסינון צריך להיות מוקף במירכאות יחידות ('). ברשימה Entity מוצגות רק ספריות ברמת הבסיס. לכן, אפשר לפרט את הקבצים שקיימים רק בספריות ברמת הבסיס. אין תמיכה בהצגת רשימה של קבצים בספריות המשנה. השדה FilePath מוגדר בסכימת ה-JSON של מטען הייעודי (payload) של הקלט. רשימה של כל השדות הזמינים מופיעה במאמר סכימת JSON למטען ייעודי (payload). אפשר להגדיר באופן דינמי את סעיף הסינון באמצעות המשימה Data Mapping (מיפוי נתונים) בשילוב.
העברת קובץ	mv /tmp/dir_A/hello_world.txt /dir_B/dir_C/	בתיבת הדו-שיח Configure connector task, לוחצים על Actions. בוחרים את הפעולה MoveFile ולוחצים על סיום. בקטע 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	בתיבת הדו-שיח Configure connector task, לוחצים על Actions. בוחרים את הפעולה RenameFile ולוחצים על סיום. בקטע 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	בתיבת הדו-שיח Configure connector task, לוחצים על Entities. ברשימה Entity, בוחרים את ספריית הבסיס שכוללת את הקובץ שרוצים להעביר. בוחרים את הפעולה Delete ולוחצים על סיום. מגדירים את מזהה הישות לנתיב המלא של הקובץ. כדי להגדיר את מזהה הישות, בקטע 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	בתיבת הדו-שיח Configure connector task, לוחצים על Actions. בוחרים את הפעולה Upload ולוחצים על סיום. בקטע Task Input (קלט של משימה) במשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value: { "Content": "This is a sample text!\r\n", "RemoteFile": "/tmp/file_1.txt", "Overwrite": true } בדוגמה הזו נוצר הקובץ file_1.txt עם התוכן This is a sample text! בספרייה /tmp של שרת ה-SFTP. כל קובץ קיים עם אותו שם יוחלף כי ערך המאפיין Overwrite הוא true. הגדרת המאפיין Overwrite היא אופציונלית. ערך ברירת המחדל הוא false. הערה: אי אפשר להעלות קובץ מקומי ישירות לשרת ה-SFTP. צריך לציין את כל התוכן של הקובץ במאפיין Content.
העלאת קובץ בינארי	put image_1.png /tmp/image_1.png	כדי להעלות תוכן בינארי, קודם צריך לקודד את התוכן בפורמט Base64. אתם יכולים לבחור כלי לפי בחירתכם כדי לקודד את התוכן. השלבים לקידוד התוכן לא נכללים במסמך הזה. אחרי שיש לכם את התוכן כמחרוזת Base64, מבצעים את השלבים הבאים: בתיבת הדו-שיח Configure connector task, לוחצים על Actions. בוחרים את הפעולה Upload ולוחצים על סיום. בקטע Task Input (קלט של משימה) במשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value: { "ContentBytes": "SGVsbG8gd29ybGQ=", "RemoteFile": "/tmp/image_1.png", "Overwrite": true, "HasBytes": true } בדוגמה הזו נוצר הקובץ image_1.png עם התוכן שצוין בשדה ContentBytes. הקובץ נוצר בספרייה /tmp של שרת ה-SFTP. כל קובץ קיים עם אותו שם יוחלף כי ערך המאפיין Overwrite הוא true. הגדרת המאפיין Overwrite היא אופציונלית. ערך ברירת המחדל הוא false.
הורדת קובץ טקסט בפורמט ASCII	get /tmp/myfile.txt	בתיבת הדו-שיח Configure connector task, לוחצים על Actions. בוחרים את הפעולה Download ולוחצים על סיום. בקטע Task Output (פלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value: { "RemoteFile": "/tmp/myfile.txt" } התוכן של הקובץ שהורד זמין כמחרוזת בשדה Content של פרמטר התגובה connectorOutputPayload של משימת המחבר.
הורדת קובץ בינארי	get /tmp/myfile.png	בתיבת הדו-שיח Configure connector task, לוחצים על Actions. בוחרים את הפעולה Download ולוחצים על סיום. בקטע Task Output (פלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value: { "RemoteFile": "/tmp/myfile.png", "HasBytes" : true } תוכן הקובץ שהורד זמין כמחרוזת בקידוד Base64 בשדה ContentBytes של פרמטר התגובה connectorOutputPayload של משימת המחבר.
הורדת מספר קבצים		בתיבת הדו-שיח Configure connector task, לוחצים על Actions. בוחרים את הפעולה Download ולוחצים על סיום. בקטע Task Output (פלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים את הפרטים הבאים בשדה Default Value: { "RemoteFile": "/tmp/myfile*.txt" } הערה: התו * הוא התו הכללי היחיד שנתמך בפרמטר RemoteFile. כשמשתמשים בתו כללי שתואם לכמה קבצים, הפעולה Download מחזירה את התוכן של קובץ אחד בלבד שתואם לתו הכללי. היא לא מחזירה את התוכן של כל הקבצים שתואמים לתו הכללי. כדי להוריד כמה קבצים, קודם צריך להשתמש בפעולה List כדי ליצור רשימה של הקבצים, ואז לבצע פעולה נפרדת של Download לכל קובץ.

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

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

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

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

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

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

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

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

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

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

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

שם הפרמטר	סוג נתונים	חובה	תיאור
remote_path	מחרוזת	לא נכון	הנתיב הנוכחי בשרת ה-SFTP.

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

לכל אובייקט ישות בחיבור SFTP יש סכימת JSON מוגדרת מראש. אובייקטים של ישויות בחיבור SFTP משתמשים בסכימת ה-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
        }
      }
    }
  

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

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

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

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