‫QuickBooks Online

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

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

לפני שמשתמשים ב-QuickBooks Online Connector, צריך לבצע את המשימות הבאות:

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

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

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

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

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

    7. מזהה החברה: צריך לציין את מזהה החברה של האפליקציה שרשומה בפורטל המפתחים של Intuit.
    8. אופציונלי: מזינים קוד מדינה למהדורה של QuickBooks Online שבה משתמשים.
    9. אופציונלי: מזינים גרסה משנית: לשימוש בשליחת בקשות ל-QuickBooks Online API.
    10. שימוש ב-Sandbox: מסמנים את התיבה אם משתמשים בחשבון Sandbox.
    11. (אופציונלי) בקטע הגדרות מתקדמות, מסמנים את התיבה שימוש ב-proxy כדי להגדיר שרת proxy לחיבור, ומגדירים את הערכים הבאים:
      • סכימת אימות של שרת proxy: בוחרים את סוג האימות לאימות מול שרת ה-proxy. אלה סוגי האימות שנתמכים:
        • בסיסי: אימות HTTP בסיסי.
        • ‫Digest: אימות HTTP מסוג Digest.
      • משתמש proxy: שם משתמש שישמש לאימות בשרת ה-proxy.
      • סיסמת ה-Proxy: הסוד במנהל הסודות של סיסמת המשתמש.
      • סוג ה-SSL של ה-Proxy: סוג ה-SSL שבו יש להשתמש כשמתחברים לשרת ה-Proxy. אלה סוגי האימות שנתמכים:
        • אוטומטי: הגדרת ברירת המחדל. אם כתובת ה-URL היא כתובת HTTPS, נעשה שימוש באפשרות Tunnel. אם כתובת ה-URL היא כתובת HTTP, נעשה שימוש באפשרות NEVER.
        • תמיד: החיבור תמיד מופעל באמצעות SSL.
        • לעולם לא: החיבור לא מופעל באמצעות SSL.
        • מנהור: החיבור הוא דרך שרת proxy למנהור. שרת ה-proxy פותח חיבור למארח המרוחק, והתנועה זורמת הלוך ושוב דרך ה-proxy.
      • בקטע שרת Proxy, מזינים את פרטי שרת ה-Proxy.
        1. לוחצים על + הוספת יעד.
        2. בוחרים סוג יעד.
          • כתובת המארח: מציינים את שם המארח או את כתובת ה-IP של היעד.

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

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

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

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

    2. לוחצים על הבא.
  6. בקטע אימות, מזינים את פרטי האימות.
    • בוחרים סוג אימות ומזינים את הפרטים הרלוונטיים.
      1. Client ID: מזהה הלקוח שמשמש לבקשת אסימוני גישה.
      2. ‫Scopes: רשימה מופרדת בפסיקים של ההיקפים הרצויים
      3. סוד לקוח: סוד ב-Secret Manager שמכיל את סוד הלקוח של האפליקציה המקושרת שיצרתם.
      4. גרסה: בוחרים את הגרסה מהתפריט הנפתח ומעניקים לה גישה.
      5. לוחצים על הבא.
  7. בדיקה: בודקים את פרטי החיבור והאימות.
  8. לוחצים על יצירה.
  9. לוחצים על Authorize.

    אם ההרשאה מתבצעת בהצלחה, סטטוס החיבור יהיה פעיל בדף החיבורים.

הגדרת אימות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

בדוגמה הזו מפורטת כל הישות Accountsassociated with the Current application of QB Online.

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

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

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

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

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

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

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות Vendors מהרשימה Entity.
  3. בוחרים את הפעולה Create ולוחצים על סיום.
  4. בקטע Task Input (קלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ואז מזינים ערך דומה לערך הבא בשדה Default Value: 
    {
{
  {
    "Id": "32",
    "SyncToken": "0",
    "MetaData_CreateTime": "2024-04-17 17:13:24.0",
    "MetaData_LastUpdatedTime": "2024-04-24 19:55:23.0",
    "Title": null,
    "GivenName": null,
    "MiddleName": null,
    "FamilyName": null,
    "Suffix": null,
    "DisplayName": "tim Telephone",
    "CompanyName": "tim Telephone",
    "PrintOnCheckName": "tim Telephone",
    "Active": true,
    "PrimaryPhone_FreeFormNumber": "(650) 555-1616",
    "AlternatePhone_FreeFormNumber": null,
    "Mobile_FreeFormNumber": null,
    "Fax_FreeFormNumber": null,
    "PrimaryEmailAddr_Address": null,
    "WebAddr_URI": null,
    "BillAddr_Id": "33",
    "BillAddr_Line1": "10 Main St.",
    "BillAddr_Line2": null,
    "BillAddr_Line3": null,
    "BillAddr_Line4": null,
    "BillAddr_Line5": null,
    "BillAddr_City": "Palo Alto",
    "BillAddr_Country": null,
    "BillAddr_CountrySubDivisionCode": "CA",
    "BillAddr_PostalCode": "94303",
    "BillAddr_Lat": "37.445013",
    "BillAddr_Long": "-122.1391443",
    "OtherContactInfo_Type": null,
    "OtherContactInfo_Telephone_FreeFormNumber": null,
    "TaxIdentifier": null,
    "TermRef": "1",
    "TermRef_Name": null,
    "Balance": "0",
    "AcctNum": null,
    "Vendor1099": false,
    "CurrencyRef": "USD",
    "CurrencyRef_Name": "United States Dollar"
  }
}

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

    {
{ "Id": "64" }
}

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

בדוגמה הזו מעדכנים את הרשומה עם המזהה שצוין בישות Purchases.

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

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

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

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות Invoices מהרשימה Entity.
  3. בוחרים את הפעולה Delete ולוחצים על סיום.
  4. לוחצים על entityId ואז מזינים 10 בשדה ערך ברירת מחדל.

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

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

    {
{Success}
}

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

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

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