DocuSign

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

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

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

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

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

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

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

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

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

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

      • OAUTH 2.0 - קוד הרשאה
      • OAuth 2.0 - JWT Bearer

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

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

הגדרת אימות

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

  • OAUTH 2.0 - קוד הרשאה
    • Client ID: מזהה הלקוח שמשמש לבקשת אסימוני גישה.
    • ‫Scopes: רשימה מופרדת בפסיקים של ההיקפים הרצויים.
    • סוד לקוח: סוד ב-Secret Manager שמכיל את סוד הלקוח של האפליקציה המקושרת שיצרתם.
    • כתובת URL לאישור: מזינים את כתובת ה-URL לאישור, למשל https://account.docusign.com/oauth/auth לחשבון הפקה או https://account-d.docusign.com/oauth/auth לחשבון ארגז חול.
  • OAuth 2.0 - JWT Bearer
    • טוקן צרכן של אפליקציה מקושרת:טוקן הצרכן שסופק לאפליקציה המקושרת שיצרתם.
    • שם משתמש: שם המשתמש שמשויך לאפליקציה המקושרת שיצרתם.
    • מפתח פרטי: סוד ב-Secret Manager שמכיל את התוכן של קובץ המפתח הפרטי. המפתח הפרטי צריך להיות תואם למפתח הציבורי או לאישור שסופקו ל-Connector.

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

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

OAUTH 2.0 – סוג החיבור Authorization Code (קוד הרשאה)

שם השדה פרטים
מיקום us-central1
מחבר DocuSign
גרסת המחבר 1
שם החיבור gcp-docusign-new-auth
הפעלת Cloud Logging לא
UseSandbox כן
חשבון השירות 123456789012-compute@developer.gserviceaccount.com
אימות ‫OAuth 2.0 – קוד הרשאה
מספר לקוח 67dxxxxx-xxxx-xxxx-xxxx-xxxxxxxcb79
היקפים חתימה
סוד לקוח CLIENT_SECRET
Secret Version 1
כתובת אתר להרשאה https://account-d.docusign.com/oauth/auth

OAuth 2.0 – סוג החיבור JWT Bearer

שם השדה פרטים
מיקום us-central1
מחבר DocuSign
גרסת המחבר 1
שם החיבור gcp-docusign-token
הפעלת Cloud Logging לא
UseSandbox כן
חשבון השירות 123456789012-compute@developer.gserviceaccount.com
אימות ‫OAuth 2.0 – JWT Bearer
טוקן צרכן של אפליקציה מקושרת 67dxxxxx-xxxx-xxxx-xxxx-xxxxxxxcb79
שם משתמש USER_NAME
מפתח פרטי PRIVATE_KEY
Secret Version 1

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

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

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

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

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

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

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

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

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

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

פעולות

בקטע הזה מפורטות כל הפעולות שנתמכות בחיבור ל-DocuSign.

פעולה CreateAndSendEnvelope

יוצר ושולח מעטפה או יוצר טיוטה של מעטפה.

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

שם הפרמטר סוג נתונים חובה תיאור
FileName String כן שם המסמך.
DocumentId String כן מזהה המסמך.
EmailSubject String כן שורת הנושא של האימייל.
תוכן String כן התוכן בקובץ.
SignersEmail String לא מזהי האימייל של בעלי החתימה על המסמך.
SignersRecipientId String לא מזהי הנמענים של החותמים.
CcRecipientId String לא מזהי הנמענים של הנמענים שהועתקו באימייל.
CcEmail String לא מזהי האימייל של הנמענים שמועתקים באימייל.
סטטוס String לא הסטטוס של המעטפה. מגדירים את הסטטוס ל'נשלח' כדי לשלוח את המעטפה לנמענים.
CustomFieldAggregate String לא אפשר להשתמש בעמודות הבאות: CustomFieldName,‏ CustomFieldId,‏ CustomFieldShow,‏ CustomFieldRequired,‏ CustomFieldValue,‏ CustomFieldConfiguration ו-CustomFieldListItems.
SignersName String לא שם החותמים על המסמך.
CcName String לא שם הנמענים בשדה 'עותק'.

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

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

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

דוגמה – CreateAndSendEnvelope

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Actions.
  2. בוחרים את הפעולה CreateAndSendEnvelope ולוחצים על סיום.
  3. בקטע Task Input (קלט המשימה) של המשימה Connectors (מחברים), לוחצים על connectorInputPayload ומזינים ערך דומה לערך הבא בשדה Default Value: 
    {
"EmailSubject": "Please Sign this Document",
"FileName": "test.txt\ntest.pdf",
"SignersEmail": "cloudysanfrancisco@gmail.com",
"SignersRecipientId": "53386460",
"CcRecipientId": "67173451",
"CcEmail": "baklavainthebalkans@gmail.com",
"DocumentId": "1",
"Status": "sent",
"CustomFieldAggregate": "CustomFieldName",
"ContentBytes": "abcd***",
"HasBytes": true,
"SignersName": "\"test\"",
"CcName": "\"test\"",
"Content": "test content in file"
}
    4. אם הפעולה מצליחה, פרמטר התגובה connectorOutputPayload של משימת המחבר יקבל ערך שדומה לזה:

     [{
"Success":"true",
"envelopeid":"542a77ff-b533-4b39-9d82-e397ef5a70c9",
"uri":"/envelopes/542a77ff-b533-4b39-9d82-e397ef5a70c9",
"statusdatetime":"2025-04-09T12:33:47.1130000Z",
"status":"sent",
"customfieldaggregate": "CustomFieldName"
}]

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

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

צריך להעביר את הערך של מזהה הישות ישירות, כמו 16ab549b-95d7-47cb-b557-c2476ef62d9d. המזהה 16ab549b-95d7-47cb-b557-c2476ef62d9d הוא ערך המפתח הראשי הייחודי שצריך להעביר.

דוגמה – פעולת LIST עבור הישות Accounts

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

דוגמה – פעולת LIST עבור הישות Documents

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

דוגמה – פעולת LIST עבור הישות Envelopes

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

דוגמה – פעולת LIST עבור הישות 'תיקיות'

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

דוגמה – פעולת LIST עבור הישות Groups

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

דוגמה – פעולת LIST עבור הישות Users

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

אפשר לבצע פעולות LIST גם על הישויות הבאות:

  • UserInfo
  • UserSignatures
  • סביבות עבודה
  • נמענים
  • AccountBrands
  • AccountCustomFields
  • EnvelopeTemplates
  • EnvelopeAttachments
  • EnvelopeConsumerDisclosures
  • CloudStorageProviders
  • CustomTabs
  • מנעולים
  • GroupBrands
  • GroupUsers
  • PowerForms
  • RecipientTabs
  • SigningGroups
  • SigningGroupUsers
  • תבניות

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות 'חשבונות' מהרשימה Entity.
  3. בוחרים את הפעולה GET ולוחצים על סיום.
  4. כדי להגדיר את מזהה הישות, בקטע Data Mapper של Data Mapping, לוחצים על Open Data Mapping Editor, מזינים 2.4578824E7 בשדה Input Value ובוחרים באפשרות EntityId בתור Local variable.

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות 'מסמכים' מהרשימה Entity.
  3. בוחרים את הפעולה LIST ולוחצים על סיום.
  4. כדי להגדיר את סעיף המסנן, בקטע Data Mapper של Data Mapping, לוחצים על Open Data Mapping Editor, מזינים Type='envelopes' AND Id='8e18be14-3254-4cbe-947d-f0d1cd62f5f8' בשדה Input Value ובוחרים את סעיף המסנן כמשתנה מקומי.

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות 'מעטפות' מהרשימה Entity.
  3. בוחרים את הפעולה GET ולוחצים על סיום.
  4. כדי להגדיר את מזהה הישות, בקטע Data Mapper של Data Mapping, לוחצים על Open Data Mapping Editor, מזינים 8e18be14-3254-4cbe-947d-f0d1cd62f5f87 בשדה Input Value ובוחרים באפשרות EntityId בתור Local variable.

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות 'תיקיות' מהרשימה Entity.
  3. בוחרים את הפעולה GET ולוחצים על סיום.
  4. כדי להגדיר את מזהה הישות, בקטע Data Mapper של Data Mapping, לוחצים על Open Data Mapping Editor, מזינים 05f76d13-a513-492b-8c58-176702768db0 בשדה Input Value ובוחרים באפשרות EntityId בתור Local variable.

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות 'קבוצות' מהרשימה Entity.
  3. בוחרים את הפעולה GET ולוחצים על סיום.
  4. כדי להגדיר את מזהה הישות, בקטע Data Mapper של Data Mapping, לוחצים על Open Data Mapping Editor, מזינים 1.4167231E7 בשדה Input Value ובוחרים באפשרות EntityId בתור Local variable.

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

  1. בתיבת הדו-שיח Configure connector task, לוחצים על Entities.
  2. בוחרים באפשרות 'משתמשים' מהרשימה Entity.
  3. בוחרים את הפעולה GET ולוחצים על סיום.
  4. כדי להגדיר את מזהה הישות, בקטע Data Mapper של Data Mapping, לוחצים על Open Data Mapping Editor, מזינים 16ab549b-95d7-47cb-b557-c2476ef62d9d בשדה Input Value ובוחרים באפשרות EntityId בתור Local variable.

אפשר גם לבצע פעולות GET על הישויות הבאות:

  • UserInfo
  • UserSignatures
  • סביבות עבודה
  • נמענים
  • AccountBrands
  • AccountCustomFields
  • EnvelopeTemplates
  • EnvelopeAttachments
  • EnvelopeConsumerDisclosures
  • CloudStorageProviders
  • CustomTabs
  • מנעולים
  • GroupBrands
  • GroupUsers
  • RecipientTabs
  • SigningGroups
  • SigningGroupUsers
  • תבניות

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

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

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

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

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

שם הפרמטר סוג נתונים חובה תיאור
proxy_enabled בוליאני לא נכון מסמנים את תיבת הסימון הזו כדי להגדיר שרת Proxy לחיבור.
proxy_auth_scheme ENUM לא נכון סוג האימות שבו יש להשתמש כדי לבצע אימות לשרת ה-proxy‏ ProxyServer. הערכים הנתמכים הם: BASIC, ‏ DIGEST, ‏ NONE
proxy_user מחרוזת לא נכון שם משתמש שישמש לאימות בשרת ה-proxy ‏ProxyServer.
proxy_password SECRET לא נכון סיסמה שתשמש לאימות בשרת ה-proxy‏ ProxyServer.

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

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

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

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

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

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