SendGrid

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

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

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

• בפרויקט שלכם ב-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)

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

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

הגדרת אימות באמצעות מפתח API

1. עוברים אל הגדרות ובוחרים באפשרות מפתחות API.
2. לוחצים על Create API Key (יצירת מפתח API).
3. מזינים שם למפתח ה-API
4. בוחרים מבין האפשרויות גישה מלאה, גישה מוגבלת או גישה לחיוב.
5. בוחרים באפשרות גישה מוגבלת או גישה לחיוב, ובוחרים את ההרשאות הספציפיות לכל קטגוריה.
6. לוחצים על יצירה ותצוגה.
7. מעתיקים את מפתח ה-API ושומרים אותו לשימוש מאוחר יותר.

הגדרת המחבר

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

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

   כניסה לדף Connections

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

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

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

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

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

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

   הערה: אפשר להתאים אישית את הערכים של צומת החיבור רק אם אתם לקוחות עם תשלום לפי שימוש.
   8. אופציונלי: לוחצים על + הוספת תווית כדי להוסיף תווית לקישור בצורה של צמד מפתח/ערך.
   9. לוחצים על הבא.
5. בקטע אימות, מזינים את פרטי האימות. מידע נוסף מופיע במאמר הגדרת אימות. |
6. לוחצים על הבא.
7. בדיקה: בודקים את פרטי החיבור והאימות.
8. לוחצים על יצירה.

הגדרת אימות

אימות באמצעות מפתח API

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

דוגמאות להגדרת חיבור

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

סוג החיבור לאינטרנט

שם השדה	פרטים
מיקום	us-central1
מחבר	Sendgrid
גרסת המחבר	1
שם החיבור	sendgrid-google-cloud-conn
חשבון השירות	SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
מספר הצמתים המינימלי	2
מספר הצמתים המקסימלי	50
מפתח API	API_KEY
Secret Version	1

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

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

הערה: אפשר לראות את הישויות, הפעולות והפעולות של מחבר במשימת המחברים.

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

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

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

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

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

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

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

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

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

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

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

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

פעולות

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

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

הפעולה SendMail2

הפעולה הזו גורמת לשליחת אימייל עם קובץ מצורף.

שדות בגוף הבקשה לפעולה SendMail2

שם השדה	סוג נתונים	חובה	תיאור
נושא	String	כן	נושא האימייל שיישלח.
ContentValue	String	לא	תוכן האימייל שרוצים לשלוח.
ContentType	String	לא	סוג התוכן שיישלח. הערכים הנתמכים הם text/plain ו-text/html.
תוכן	String	כן	הצבירה של אובייקט התוכן.
SendAt	String	לא	התאריך והשעה שבהם רוצים שהאימייל יימסר. אסור לתזמן יותר מ-72 שעות מראש.
FromEmail	String	כן	כתובת האימייל של השולח.
FromName	String	לא	השם של השולח.
ToEmail	String	לא	כתובת האימייל שאליה יישלח האימייל.
ToName	String	לא	השמות המתאימים של כתובות האימייל שאליהן רוצים לשלוח את האימייל.
אל	String	לא	הנתון המצטבר של נמענים בשדה 'אל'.
ToCCEmail	String	לא	כתובות האימייל של הנמענים שיקבלו עותק של האימייל.
ToCCName	String	לא	שם הנמענים שיקבלו עותק של האימייל.
ToBCCName	String	לא	השם של הנמענים שיקבלו עותק מוסתר של האימייל.
ToBCC	String	לא	הצבירה של הנמענים בשדה 'עותק מוסתר'.
ReplyToEmail	String	לא	כתובת האימייל של האדם שאליו משיבים.
ReplyToName	String	לא	השם של האדם שאליו משיבים.
AttachmentPaths	String	לא	הנתיב של הקובץ לצירוף לאימייל שיישלח.
TemplateId	String	כן	המזהה של התבנית שרוצים לשלוח.
DynamicTemplateData	String	לא	הנתונים של התבנית הדינמית.
התאמות אישיות	String	כן	מערך של הודעות והמטא-נתונים שלהן. אפשר לחשוב על כל אובייקט בהתאמה אישית כמעטפה – הוא מגדיר מי צריך לקבל הודעה אישית ואיך צריך לטפל בהודעה הזו.

פרמטרים של פלט של הפעולה 'שליחת אימייל'

הפעולה הזו מחזירה הודעת אישור, בין אם האימייל נשלח בהצלחה ובין אם לא.

דוגמאות לפעולות

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

דוגמה – שליחת אימייל

1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
2. בוחרים את הפעולה SendMail2 ולוחצים על סיום.
3. בקטע Task Input (קלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים ערך דומה לערך הבא בשדה Default Value:

   {
       "FromName": "Name",
       "FromEmail": "[e-mail]",
       "Subject": "[{\"value\": \"cymbalgroup.com\",\"type\": \"text/plain\"}]",
       "TemplateId": "d-c4bc730a0b094a3a9d9cabb7347b5edc",
       "Personalizations": "[{\"subject\": \"Test Subject3\",\"send_at\": 1698659820,\"from\": {\"name\": \"hi\",\"email\": \"email@gmail\"},\"to\":      
       [{\"email\": \"[e-mail]\",\"name\": \"test\"}\n ]}]",
       "Content": "[{\"value\": \"[e-mail]\",\"type\": \"text/plain\"}]"
   }

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

[{
"Success": "True"
}]

דוגמאות לפעולות על ישויות

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

דוגמה – הצגת כל אנשי הקשר

בדוגמה הזו מפורטים כל אנשי הקשר בישות NMCContacts.

1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
2. בוחרים באפשרות NMCContacts מהרשימה Entity.
3. בוחרים את הפעולה List ולוחצים על סיום.
4. אופציונלי: בקטע Task Input (קלט משימה) במשימה Connectors (מחברים), אפשר לסנן את קבוצת התוצאות על ידי ציון filter clause (סעיף סינון). לדוגמה, City='Bangalore'. אפשר גם לציין כמה תנאי סינון באמצעות אופרטורים לוגיים. לדוגמה, City='Bangalore' and region='asia-south2'.

דוגמה – קבלת רשומה

בדוגמה הזו מאחזרים רשומה עם המזהה שצוין מהישות NMCSegments.

1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
2. בוחרים באפשרות NMCSegments מהרשימה Entity.
3. בוחרים את הפעולה Get ולוחצים על סיום.
4. בקטע Task Input (קלט של המשימה) במשימה Connectors (מחברים), לוחצים על EntityId (מזהה הישות) ואז מזינים 0d44bb3f-d28e-4bcf-aba2-c77be831ad46 בשדה Default Value (ערך ברירת המחדל).

   כאן, 0d44bb3f-d28e-4bcf-aba2-c77be831ad46 הוא ערך של מפתח ראשי בישות NMCSegments.

דוגמה – יצירת רשומה

בדוגמה הזו נוצרת רשומה בישות NMCSenders.

1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
2. בוחרים באפשרות NMCSenders מהרשימה Entity.
3. בוחרים את הפעולה Create ולוחצים על סיום.
4. בקטע Task Input (קלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים ערך דומה לערך הבא בשדה Default Value:

   {
   "Nickname": "Test",
   "FromEmail": "[e-mail]",
   "FromName": "testuser",   
   "ReplytoEmail": "[e-mail]",  
   "Address": "NA", 
   "City": "NA", 
   "Country": "India"}

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

   {
   "Id": 5360940.0
   }

דוגמה – יצירת רשומה

בדוגמה הזו נוצרת רשומה בישות NMCLists.

1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
2. בוחרים באפשרות NMCLists מהרשימה Entity.
3. בוחרים את הפעולה Create ולוחצים על סיום.
4. בקטע Task Input (קלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים ערך דומה לערך הבא בשדה Default Value:

   {
   "Name": "TEST_CON_LIST1699262238224",
   "ContactCount": 3.0}

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

   {
   "Id": "d927f128-b718-447a-affe-417f1a8b3abd"}

דוגמה – עדכון רשומה

בדוגמה הזו מעדכנים רשומה בישות NMCSenders.

1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
2. בוחרים באפשרות NMCSenders מהרשימה Entity.
3. בוחרים את הפעולה Update ולוחצים על סיום.
4. בקטע Task Input (קלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים ערך דומה לערך הבא בשדה Default Value:

   {
   "Nickname": "Test",
   "FromEmail": "[e-mail]",
   "FromName": "testuser",   
   "ReplytoEmail": "[e-mail]",  
   "Address": "NA", 
   "City": "NA", 
   "Country": "India"}

5. לוחצים על entityId ואז מזינים 5360940.0 בשדה ערך ברירת מחדל.

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

   {
   "Id":"5360940.0"
   }

דוגמה – מחיקת רשומה

בדוגמה הזו נמחק הרשומה עם המזהה שצוין בישות NMCSegments.

1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
2. בוחרים באפשרות NMCSegments מהרשימה Entity.
3. בוחרים את הפעולה Delete ולוחצים על סיום.
4. בקטע Task Input (קלט משימה) של המשימה Connectors (מחברים), לוחצים על entityId ואז מזינים c58b9151-7279-428a-bac2-12b4bf2b48b0 בשדה Default Value (ערך ברירת מחדל).

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

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

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

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

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

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

שם הפרמטר	סוג נתונים	חובה	תיאור

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

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

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

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

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

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

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