ZohoBooks

המחבר ZohoBooks מאפשר לבצע פעולות SQL במערכת ZohoBooks.

גרסאות נתמכות

המחבר משתמש ב-Zoho Books API V3 כדי לאפשר גישה דו-כיוונית לנתונים של Zoho Books.

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

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

• בפרויקט שלכם ב-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. מחבר: בוחרים באפשרות Zoho Books מהרשימה הנפתחת של המחברים הזמינים.
   2. גרסת כלי החיבור: בוחרים את גרסת כלי החיבור מהרשימה הנפתחת של הגרסאות הזמינות.
   3. בשדה Connection Name (שם החיבור), מזינים שם למופע החיבור.

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

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

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

   הערה: אפשר להתאים אישית את הערכים של צומת החיבור רק אם אתם לקוחות עם תשלום לפי שימוש.
   8. שרת חשבונות: כתובת ה-URL המלאה של שרת החשבונות.
   9. מזהה הארגון: המזהה שמשויך לארגון הספציפי ב-Zoho Books.
   10. רמת הפירוט: רמת הפירוט של החיבור, משתנה מ-1 עד 5. רמת פירוט גבוהה יותר תתעד את כל פרטי התקשורת (בקשה,תגובה ואישורי SSL).
   11. אופציונלי: לוחצים על + הוספת תווית כדי להוסיף תווית לקישור בצורה של צמד מפתח/ערך.
   12. לוחצים על הבא.
5. בקטע אימות, מזינים את פרטי האימות.
   1. בוחרים סוג אימות ומזינים את הפרטים הרלוונטיים.

      החיבור ל-Zoho Books תומך בסוגי האימות הבאים:

      • הרשאת קוד אימות OAuth 2.0

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

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

הגדרת אימות

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

• הרשאת קוד אימות OAuth 2.0
  • מזהה לקוח: מזהה הלקוח שסופק על ידי כלי החיבור לאפליקציה שיצרתם.
  • סוד הלקוח: סוד ב-Secret Manager שמכיל את סוד הלקוח של האפליקציה המקושרת שיצרתם.
  • Access Token: סוד ב-Secret Manager שמכיל את אסימון הגישה של OAuth שסופק לאפליקציה המקושרת שיצרתם.

הגדרת אימות ב-ZohoBooks

בקטעים הבאים מוסבר איך להגדיר את המחבר של ZohoBooks.

הגדרת חשבון ZohoBooks

מידע נוסף על הגדרת חשבון ZohoBooks זמין במאמר בנושא יצירת חשבון.

הגדרת חשבון פיתוח ויצירת אפליקציית לקוח

מידע על חשבון פיתוח ב-ZohoBooks ועל יצירת אפליקציית לקוח זמין במאמר יצירת אפליקציית לקוח.

מגדירים אימות

כדי להגדיר אימות:

1. נכנסים לדף Integration Connectors במסוף Cloud.
2. כדי לראות את הפרטים של חיבור ספציפי, לוחצים על שם החיבור בטבלה של החיבורים הקיימים.
3. בקטע אימות, לוחצים על אישור החיבור כדי להתחיל בתהליך ההרשאה.
4. מעתיקים את ה-URI של ההפניה האוטומטית.
5. עוברים אל ZohoBooks Developer Console.
6. בקטע Service based application client authorized redirect URI's (הפניה אוטומטית לכתובת URI אחרת של לקוח אפליקציה שמבוססת על שירות), מוסיפים את כתובת ה-URI להפניה אוטומטית.
כשמגדירים את אפליקציית ה-OAuth של צד שלישי, צריך להשתמש בכתובת ה-URI המורשית להפניה אוטומטית (כתובת ה-URL של הקריאה החוזרת):

https://console.cloud.google.com//connectors/oauth?project=PROJECT_ID

מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud .

7. בדף Integration Connectors (מחברי שילוב), עוברים לדף החיבור של ZohoBooks שממנו העתקתם את ה-URI של ההפניה האוטומטית ולוחצים על Authorize (אישור).

תועברו לאתר ZohoBooks כדי לאשר את הגישה.

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

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

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

שם השדה	פרטים
אזור	us-east4
מחבר	ZohoBooks
גרסת המחבר	1
שם החיבור	zohobooks-google-cloud-conn
חשבון השירות	SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
שרת חשבונות	https://books.zoho.in
מזהה הארגון	ORGANIZATION_ID
דרגת המלל	5
מספר הצמתים המינימלי	2
מספר הצמתים המקסימלי	50
מספר לקוח	CLIENT_ID
היקפים	ZohoBooks.fullaccess.all
סוד לקוח	CLIENT_SECRET
גרסה של סוד	1

שימוש בחיבור ל-ZohoBooks בשילוב

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

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

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

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

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

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

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

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

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

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

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

פעולות

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

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

פעולת ייבוא של דפי חשבון של כרטיסי אשראי

הפעולה הזו מאפשרת לייבא דפי חשבון של כרטיסי אשראי.

פרמטרים של קלט לפעולה ImportCreditCardStatement

שם הפרמטר	סוג נתונים	חובה	תיאור
AccountId	String	לא	מזהה של חשבון בנק או כרטיס אשראי
TransactionsTransactionDebitOrCredit	String	לא	מציין אם העסקה היא חיוב או זיכוי.
TransactionsTransactionAmount	String	לא	הסכום שמשויך לעסקה.
TransactionsTransactionDescription	String	לא	תיאור העסקה.
TransactionsTransactionDate	String	לא	תאריך העסקה.

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

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

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

דוגמה – ייבוא של פירוט העסקאות בכרטיס אשראי

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

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

   {
     "AccountId": "1470449000000023015",
     "TransactionsTransactionDebitOrCredit": "credit",
     "TransactionsTransactionAmount": "200",
     "TransactionsTransactionDescription": "Transaction done from Google account",
     "TransactionsTransactionDate": "2023-05-05"
   }

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

[{
"Status": "Your bank statement has been imported."
}]

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

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

דוגמה – הצגת כל האומדנים

בדוגמה הזו מוצגת רשימה של כל הרשומות בישות Estimates.

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

דוגמה – קבלת הזמנת מכירות

בדוגמה הזו מתקבלת הזמנת המכירה שצוינה מהישות SalesOrder.

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

   כאן, 1470449000000043003 הוא ערך של מפתח ראשי בישות SalesOrder.

דוגמה – יצירת תנועה בנקאית

בדוגמה הזו נוצרת רשומת עסקה בנקאית בישות BankTransactions.

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

   {
   "TransactionType": "transfer_fund",
   "FromAccountId": "1470449000000000459",
   "ToAccountId": "1470449000000110001",
   "Amount": 45.0,
   "CurrencyId": "1470449000000000064"
   }

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

   {
   "TransactionId": "1470449000000231005"
   }

דוגמה – עדכון הפרטים ליצירת קשר של לקוח

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

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

   {
   "Department": "Development",
   "ContactId": "1470449000000038003"
   }

5. בקטע Task Input (קלט של משימה) במשימה Connectors (מחברים), לוחצים על entityId ואז מזינים 1470449000000038005 בשדה Default Value (ערך ברירת מחדל).

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

{
"CustomerContactId": "1470449000000038005"
}

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

בדוגמה הזו נמחק רשומה ספציפית של חשבונית בישות InvoiceDetails.

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

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

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

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

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

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