Couchbase

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

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

• ‫Couchbase Server מגרסה 4.0 ואילך (מהדורת Enterprise או מהדורת Community).

• Couchbase Capella

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

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

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

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

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

• אם צריך, יוצרים שרת Couchbase. מידע נוסף זמין במאמר מדריך למתחילים ל-Couchbase Server.
מידע על ממשקי ה-API של Couchbase זמין במסמכי התיעוד של Couchbase API בארכיטקטורת REST.
• אם נדרש, מורידים את אישור ה-SSL. מידע נוסף זמין במאמר בנושא חיבור מאובטח באמצעות TLS.

הגדרת המחבר

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

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

   כניסה לדף Connections

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

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

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

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

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

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

   הערה: אפשר להתאים אישית את הערכים של צומת החיבור רק אם אתם לקוחות עם תשלום לפי שימוש.
   8. הרשאה לשימוש בפרמטרים בפורמט JSON: מאפשרת להשתמש ב-JSON גולמי בפרמטרים כשהאפשרות QueryPassthrough מופעלת.
   9. ‫Analytics Port: היציאה לחיבור לנקודת הקצה של Couchbase Analytics.
   10. מפריד של טבלאות צאצא: התו או התווים שמשמשים לציון טבלאות צאצא.
   11. ‫Couchbase Service: קובע את שירות Couchbase שאליו מתחברים. ברירת המחדל היא N1QL. האפשרויות הזמינות הן N1QL ו-Analytics.
   12. Create Table Ram Quota: מכסת ה-RAM שמוגדרת כברירת מחדל, במגה-בייט, לשימוש כשמוסיפים באקטים באמצעות התחביר CREATE TABLE.
   13. מפריד Dataverse: התו או התווים שמשמשים לציון של Dataverse ושל היקפים או אוספים ב-Analytics.
   14. מפריד טעמים: התו או התווים שמציינים את הטעמים.
   15. יציאת N1QL: היציאה להתחברות לנקודת הקצה של Couchbase N1QL.
   16. מפריד נקודות: התו או התווים שמשמשים לציון היררכיה.
   17. Query Execution Timeout: ההגדרה הזו קובעת את הזמן הקצוב לתפוגה של השאילתה בצד השרת. היא קובעת כמה זמן Couchbase יבצע את השאילתה לפני שיחזיר שגיאת זמן קצוב לתפוגה.
   18. השוואה מדויקת: משנה את רמת הדיוק של תרגום המסננים בשאילתות קלט של SQL לשאילתות של Couchbase. אפשר להגדיר את הערך הזה כרשימה של ערכים שמופרדים בפסיקים, כאשר כל ערך יכול להיות אחד מהסוגים הבאים: תאריך, מספר, ערך בוליאני או מחרוזת.
   19. עמידות העסקה: מציין איך צריך לאחסן מסמך כדי שהעסקה תצליח. ההגדרה קובעת אם להשתמש בעסקאות N1QL כשמבצעים שאילתות.
   20. Transaction Timeout: ההגדרה הזו קובעת את משך הזמן שבו אפשר לבצע טרנזקציה לפני ש-Couchbase מפסיק אותה בגלל חריגה מזמן קצוב.
   21. Use Collections For DDL (שימוש באוספים עבור DDL): האם להניח שהצהרות CREATE TABLE משתמשות באוספים במקום בטעמים. המדיניות הזו תקפה רק כשמתחברים ל-Couchbase גרסה 7 ומעלה, וההגדרה GenerateSchemaFiles מוגדרת ל-OnCreate.
   22. Use Transactions (שימוש בטרנזקציות): מציין אם להשתמש בטרנזקציות N1QL כשמריצים שאילתות.
   23. אימות פרמטרים של JSON: מאפשר לספק לאמת שפרמטרים של מחרוזות הם JSON תקין לפני שליחת השאילתה אל Couchbase.
   24. (אופציונלי) בקטע הגדרות מתקדמות, מסמנים את התיבה שימוש ב-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 של היעד.

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

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

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

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

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

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

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

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

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

הגדרת אימות

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

• שם משתמש וסיסמה
  • שם משתמש: שם המשתמש של המחבר
  • סיסמה: סוד ב-Secret Manager שמכיל את הסיסמה שמשויכת למחבר.
  • ‫UseSSL: השדה הזה קובע אם SSL מופעל.
  • ‫SSLServerCert: SSLServerCert for Couchbase Connector
  • Auth scheme: Auth scheme for Couchbase Connector
  • מצב חיבור: קובע את אופן ההתחברות לשרת Couchbase. הערך חייב להיות Direct או Cloud. חובה להשתמש ב-SSL בשדה Cloud. מידע נוסף זמין במאמר חיבורים מאובטחים עם TLS.
  • שרת DNS: קובע באיזה שרת DNS להשתמש כשמאחזרים מידע מ-Couchbase Cloud. לדוגמה, 8.8.8.8.

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

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

SSL – סוג החיבור לאישור

שם השדה	פרטים
אזור	us-central1
מחבר	Couchbase
גרסת המחבר	1
שם מחבר	Couchbase-basic-auth-conn
חשבון השירות	[e-mail]
רמת הפירוט	5
הגדרות של צומת חיבור: מספר מינימלי/מקסימלי של צמתים	2/50
הגדרת SSL הפעלת SSL	נכון
מאגר אישורים	פרטי
מאגר אישורים בהתאמה אישית	אישור PEM מלא (‎-----BEGIN CERTIFICATE----- MIIChTCCAe4CAQAwDQYJKoZIhv......Qw== -----END CERTIFICATE-----‎)
גרסה של סוד	1
כתובת המארח	xx.1HOST_NAME.cloud.couchbase.com:18xxx
אימות	סיסמת משתמש
שם משתמש	שם משתמש
סיסמה	סיסמה
גרסאות	1
מצב חיבור	Cloud
שרת DNS	‫192.0.2.0
סכמת OAuth	בסיסי

סוג החיבור של Analytics Couchbase

שם השדה	פרטים
אזור	us-central1
מחבר	Couchbase
גרסת המחבר	1
שם מחבר	Couchbase-basic-auth-Analytics-conn
חשבון השירות	[e-mail]
ייצוא נתונים מ-Analytics	18095
Couchbase Service	Analytics
רמת הפירוט	5
הגדרות של צומת חיבור: מספר מינימלי/מקסימלי של צמתים	2/50
כתובת המארח	xx.1HOST_NAME.cloud.couchbase.com:18095
אימות	סיסמת משתמש
שם משתמש	שם משתמש
סיסמה	סיסמה
גרסאות	1
מצב חיבור	Cloud
שרת DNS	‫192.0.2.0
סכמת OAuth	בסיסי

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

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

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

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

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

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

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

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

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

פעולות

המחבר הזה תומך בביצוע הפעולות הבאות:

• פונקציות ותהליכים מאוחסנים שמוגדרים על ידי המשתמש. אם יש לכם פרוצדורות מאוחסנות ופונקציות בקצה העורפי, הן מפורטות בעמודה Actions של תיבת הדו-שיח Configure connector task.
• שאילתות SQL בהתאמה אישית. כדי להריץ שאילתות SQL מותאמות אישית, המחבר מספק את הפעולה Execute custom query (הרצת שאילתה מותאמת אישית).

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

  1. פועלים לפי ההוראות המפורטות ל הוספת משימה של מחברים.
  2. כשמגדירים את משימת המחבר, בוחרים באפשרות פעולות בסוג הפעולה שרוצים לבצע.
  3. ברשימה Action, בוחרים באפשרות Execute custom query ולוחצים על Done.

     

  4. מרחיבים את הקטע Task input (קלט למשימה) ומבצעים את הפעולות הבאות:
     1. בשדה Timeout after, מזינים את מספר השניות להמתנה עד להפעלת השאילתה.

        ערך ברירת המחדל: 180 שניות.

     2. בשדה Maximum number of rows (מספר השורות המקסימלי), מזינים את מספר השורות המקסימלי שיוחזר ממסד הנתונים.

        ערך ברירת המחדל: 25.

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

        

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

        אפשר להשתמש בסימן שאלה (?) בהצהרת SQL כדי לייצג פרמטר יחיד שצריך לציין ברשימת פרמטרים של שאילתה. לדוגמה, שאילתת ה-SQL הבאה בוחרת את כל השורות מהטבלה Employees שתואמות לערכים שצוינו בעמודה LastName:

        SELECT * FROM Employees where LastName=?

        הערה: המערכת תומכת בהצהרות של שפת טיפול בנתונים (DML) ושפת הגדרת נתונים (DDL).
     5. אם השתמשתם בסימני שאלה בשאילתת ה-SQL, צריך להוסיף את הפרמטר על ידי לחיצה על + הוספת שם פרמטר לכל סימן שאלה. במהלך ההפעלה של השילוב, הפרמטרים האלה מחליפים את סימני השאלה (?) בשאילתת ה-SQL באופן עקבי. לדוגמה, אם הוספתם שלושה סימני שאלה (?), אתם צריכים להוסיף שלושה פרמטרים לפי הסדר.

        

        כדי להוסיף פרמטרים של שאילתה:

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

     הפעולה Execute custom query לא תומכת במשתני מערך.

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

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

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

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

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

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

פעולות

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

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

פעולת AddDocument

הפעולה הזו מוסיפה מסמכים ב-Couchbase.

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

שם הפרמטר	סוג הנתונים	חובה	תיאור
BucketName	String	כן	הקטגוריה שאליה רוצים להוסיף את המסמך.
SourceTable	אובייקט	לא	השם של הטבלה הזמנית שמכילה את העמודות ID ו-Document. חובה אם לא מציינים מזהה.
מזהה	String	לא	המפתח הראשי להוספת המסמך. חובה אם לא צוין SourceTable.
מסמך	String	לא	טקסט ה-JSON של המסמך שרוצים להוסיף. חובה אם לא צוין SourceTable.

פרמטרים של פלט של הפעולה AddDocument

הפעולה הזו מחזירה את הסטטוס 200 (OK) אם היא בוצעה בהצלחה.

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

הפעולה CreateCollection

הפעולה הזו יוצרת אוסף בהיקף קיים.

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

שם הפרמטר	סוג הנתונים	חובה	תיאור
קטגוריה	String	כן	השם של הקטגוריה שמכילה את האוסף.
היקף	String	כן	השם של ההיקף שמכיל את האוסף.
שם	String	כן	השם של האוסף שרוצים ליצור.

פרמטרים של הפלט של הפעולה CreateCollection

הפעולה הזו מחזירה את הסטטוס 200 (OK) אם היא בוצעה בהצלחה.

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

הפעולה DeleteCollection

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

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

שם הפרמטר	סוג הנתונים	חובה	תיאור
קטגוריה	מחרוזת	נכון	השם של הקטגוריה שמכילה את האוסף.
היקף	String	נכון	השם של ההיקף שמכיל את האוסף.
שם	מחרוזת	נכון	השם של האוסף שרוצים למחוק.

פרמטרים של פלט של הפעולה DeleteCollection

הפעולה הזו מחזירה את הסטטוס 200 (OK) אם היא בוצעה בהצלחה.

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

פעולת CreateScope

הפעולה הזו יוצרת היקף בקטגוריה קיימת.

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

שם הפרמטר	סוג הנתונים	חובה	תיאור
קטגוריה	String	כן	שם הקטגוריה שמכילה את ההיקף
שם	String	כן	השם של ההיקף שרוצים ליצור.

פרמטרים של פלט של הפעולה CreateScope

הפעולה הזו מחזירה את הסטטוס 200 (OK) אם היא בוצעה בהצלחה.

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

פעולת DeleteScope

הפעולה הזו מוחקת היקף ואת כל האוספים שלו.

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

שם הפרמטר	סוג הנתונים	חובה	תיאור
קטגוריה	String	כן	שם הקטגוריה שמכילה את ההיקף.
שם	String	כן	שם ההיקף שרוצים למחוק.

פרמטרים של פלט של הפעולה DeleteScope

הפעולה הזו מחזירה את הסטטוס 200 (OK) אם היא בוצעה בהצלחה.

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

הפעולה ListIndices

הפעולה הזו מציגה רשימה של כל האינדקסים שזמינים ב-Couchbase.

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

לא רלוונטי

פרמטרים של פלט של הפעולה ListIndices

הפעולה הזו מחזירה את הסטטוס 200 (OK) אם היא בוצעה בהצלחה.

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

פעולת ManageIndices

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

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

שם הפרמטר	סוג הנתונים	חובה	תיאור
BucketName	String	כן	קטגוריית היעד שממנה יוצרים את האינדקס או שבה משחררים את האינדקס.
ScopeName	אובייקט	לא	היקף היעד ליצירה או להסרה של האינדקס (Couchbase גרסה 7 ואילך)
CollectionName	String	לא	אוסף היעד שממנו רוצים ליצור את האינדקס או להסיר אותו (גרסה 7 ואילך של Couchbase)
פעולה	String	כן	מציין איזו פעולה לבצע באינדקס. האפשרויות הן Create (יצירה) או Drop (הסרה).
ביטויים	String	לא	רשימה של ביטויים או פונקציות, שמקודדת כ-JSON, שהאינדקס יתבסס עליהם. צריך להגדיר לפחות אחד אם המאפיין IsPrimary מוגדר כ-false והפעולה היא Create.
שם	String	לא	שם האינדקס שרוצים ליצור או להסיר. חובה אם הערך של IsPrimary הוא false.
IsPrimary	String	לא	מציין אם האינדקס צריך להיות אינדקס ראשי.ערך ברירת המחדל הוא true.
מסננים	String	לא	רשימה של מסננים, שמקודדים כ-JSON, להחלה על האינדקס.
IndexType	String	לא	סוג האינדקס שרוצים ליצור, יכול להיות GSI או View. משתמשים בו רק אם הפעולה היא Create. ערך ברירת המחדל הוא GSI.
ViewName	String	לא	הוצא משימוש, כלול לצורך תאימות בלבד. לא עושה כלום.
צמתים	String	לא	רשימה, שמקודדת כ-JSON, של צמתים שיכילו את האינדקס, וחייבת להכיל את היציאה. בשימוש רק אם הפעולה היא Create.
NumReplica	String	לא	כמה עותקים משוכפלים ליצור בין צמתי האינדקס באשכול.

פרמטרים של פלט של הפעולה ManageIndices

הפעולה הזו מחזירה את הסטטוס 200 (OK) אם היא בוצעה בהצלחה.

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

פעולת ExecuteCustomQuery

הפעולה הזו מאפשרת להריץ שאילתה בהתאמה אישית.

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

1. פועלים לפי ההוראות המפורטות ל הוספת משימה של מחברים.
2. כשמגדירים את משימת המחבר, בוחרים באפשרות פעולות בסוג הפעולה שרוצים לבצע.
3. ברשימה Action, בוחרים באפשרות Execute custom query ולוחצים על Done.

   

4. מרחיבים את הקטע Task input (קלט למשימה) ומבצעים את הפעולות הבאות:
   1. בשדה Timeout after, מזינים את מספר השניות להמתנה עד להפעלת השאילתה.

      ערך ברירת המחדל: 180 שניות.

   2. בשדה Maximum number of rows (מספר השורות המקסימלי), מזינים את מספר השורות המקסימלי שיוחזר ממסד הנתונים.

      ערך ברירת המחדל: 25.

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

      

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

      אפשר להשתמש בסימן שאלה (?) בהצהרת SQL כדי לייצג פרמטר יחיד שצריך לציין ברשימת פרמטרים של שאילתה. לדוגמה, שאילתת ה-SQL הבאה בוחרת את כל השורות מהטבלה Employees שתואמות לערכים שצוינו בעמודה LastName:

      SELECT * FROM Employees where LastName=?

      הערה: המערכת תומכת בהצהרות של שפת טיפול בנתונים (DML) ושפת הגדרת נתונים (DDL).
   5. אם השתמשתם בסימני שאלה בשאילתת ה-SQL, צריך להוסיף את הפרמטר על ידי לחיצה על + הוספת שם פרמטר לכל סימן שאלה. במהלך ההפעלה של השילוב, הפרמטרים האלה מחליפים את סימני השאלה (?) בשאילתת ה-SQL באופן עקבי. לדוגמה, אם הוספתם שלושה סימני שאלה (?), אתם צריכים להוסיף שלושה פרמטרים לפי הסדר.

      

      כדי להוסיף פרמטרים של שאילתה:

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

   הפעולה Execute custom query לא תומכת במשתני מערך.

אם הפעולה בוצעה ללא שגיאות, היא מחזירה את הסטטוס 200 (OK) עם גוף תגובה שכולל את תוצאות השאילתה.

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

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

דוגמה – הוספת מסמך

בדוגמה הזו מוסיפים מסמך לקטגוריה ב-Couchbase.

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

   {
   "Document": "{\"ID\":10,\"Name\":\"TestDoc\"}",
   "BucketName": "CouchbaseTestBucket",
   "ID": "Test"
   }

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

[{
"RowsAffected": "1"
}]

דוגמה – יצירת אוסף

בדוגמה הזו נוצר אוסף.

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

   {
   "bucket": "CouchbaseTestBucket",
   "scope": "TestScope",
   "name": "CollectionFromGoogleCloud"
   }

בדוגמה הזו נוצר אוסף תחת TestScope. אם הפעולה מצליחה, ערך הפרמטר CreateCollection response connectorOutputPayload של המשימה יהיה דומה לדוגמה הבאה:

[{
"Success": true,
"scope": null,
"uid": null,
"collection": null,
"collections.uid": null,
"maxTTL": null,
"history": null
}]

דוגמה – מחיקת אוסף

בדוגמה הזו נמחק אוסף.

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

   {
   "bucket": "CouchbaseTestBucket",
   "scope": "TestScope",
   "name": "CollectionFromGoogleCloud"
   }

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

[{
"Success": true,
"uid": "12"
}]

דוגמה – יצירת היקף

בדוגמה הזו נוצר היקף.

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

   {
   "bucket": "CouchbaseTestBucket",
   "name": "ScopeFromGoogleCloud"
   }

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

[{
"Success": true,
"name": null,
"uid": null,
"collections": null,
"collections.name": null,
"collections.uid": null,
"collections.maxTTL": null,
"collections.history": null
}]

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

בדוגמה הזו מוסר היקף הרשאות.

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

   {
   "bucket": "CouchbaseTestBucket",
   "name": "ScopeFromGoogleCloud"
   }

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

[{
"Success": true,
"uid": "10"
}]

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

בדוגמה הזו מוצגת רשימה של כל האינדקסים שזמינים ב-Couchbase.

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

   {
   }

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

[{
"id": "3d8a78cd2e302ac2",
"datastore_id": "http://127.0.0.1:8091",
"namespace_id": "default",
"bucket_id": null,
"scope_id": null,
"keyspace_id": "CouchbaseTestBucket",
"index_key": "",
"condition": null,
"is_primary": "false",
"name": "test",
"state": "online",
"using": "gsi"
}, {
"id": "d6ce8c103b97a00d",
"datastore_id": "http://127.0.0.1:8091",
"namespace_id": "default",
"bucket_id": "CouchbaseTestBucket",
"scope_id": "TestScope",
"keyspace_id": "CouchBaseDatatypes",
"index_key": "",
"condition": null,
"is_primary": "true",
"name": "#primary",
"state": "online",
"using": "gsi"
},
{
"id": "58c25aef49dd32b3",
"datastore_id": "http://127.0.0.1:8091",
"namespace_id": "default",
"bucket_id": "CouchbaseTestBucket",
"scope_id": "TestScope",
"keyspace_id": "TestCollection",
"index_key": "",
"condition": null,
"is_primary": "false",
"name": "SearchIndexTest_1",
"state": "online",
"using": "fts"
}]

דוגמה – ניהול אינדקסים

בדוגמה הזו נמחק אינדקס בקטגוריה שצוינה.

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

   {
   "BucketName": "CouchbaseTestBucket",
   "Action": "DROP",
   "Name": "CouchBaseTestIndex"
   }

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

[{
"Success": "true"
}]

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

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

דוגמה – הצגת כל הרשומות

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

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

הערה: כדי להחיל מסנן על שדה מקונן, צריך להוסיף מירכאות כפולות (") סביב שם השדה. לדוגמה, כדי לסנן שדה מקונן geo.accuracy, משתמשים בסעיף המסנן "geo.accuracy" IN ("RANGE_INTERPOLATED", "ROOFTOP").

דוגמה – אחזור רשומה מישות

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

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

   כאן, 120 הוא מזהה רשומה ייחודי בישות TestCollection.

דוגמה – עדכון רשומה בישות

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

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

   {
   "COL_TEXT": "CouchBase Update"
   }

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

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

   [{
   "Document.Id": "120"
   }]

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

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

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

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

בעיות מוכרות

אין תמיכה בפעולה create בישויות.

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

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

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

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

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

שם הפרמטר	סוג נתונים	חובה	תיאור
allow_jsonparameters	בוליאני	לא נכון	מאפשר להשתמש ב-JSON גולמי בפרמטרים כשהאפשרות QueryPassthrough מופעלת.
analytics_port	מחרוזת	לא נכון	היציאה לחיבור לנקודת הקצה של Couchbase Analytics.
child_separator	מחרוזת	לא נכון	התו או התווים שמשמשים לציון טבלאות צאצא.
couchbase_service	ENUM	לא נכון	קובע את שירות Couchbase שאליו מתחברים. ברירת המחדל היא N1QL. האפשרויות הזמינות הן N1QL ו-Analytics. הערכים הנתמכים הם: N1QL, ‏ Analytics
create_table_ram_quota	מחרוזת	לא נכון	מכסת ה-RAM שמוגדרת כברירת מחדל, במגה-בייט, לשימוש כשמוסיפים מאגרי מידע באמצעות התחביר CREATE TABLE.
dataverse_separator	מחרוזת	לא נכון	התו או התווים שמשמשים לציון מרחבי נתונים, היקפים או אוספים ב-Analytics.
flavor_separator	מחרוזת	לא נכון	התו או התווים שמשמשים לציון טעמים.
n1_qlport	מחרוזת	לא נכון	היציאה להתחברות לנקודת הקצה של Couchbase N1QL.
periods_separator	מחרוזת	לא נכון	התו או התווים שמשמשים לציון היררכיה.
query_execution_timeout	מחרוזת	לא נכון	ההגדרה הזו קובעת את הזמן הקצוב לתפוגה בצד השרת של השאילתה, כלומר כמה זמן Couchbase יבצע את השאילתה לפני שיחזיר שגיאת זמן קצוב לתפוגה.
strict_comparison	מחרוזת	לא נכון	ההגדרה הזו קובעת את רמת הדיוק של תרגום המסננים בשאילתות קלט של SQL לשאילתות Couchbase. אפשר להגדיר את הערך הזה כרשימה של ערכים שמופרדים בפסיקים, כאשר כל ערך יכול להיות אחד מהסוגים הבאים: תאריך, מספר, ערך בוליאני או מחרוזת.
transaction_durability	מחרוזת	לא נכון	מציין איך צריך לאחסן מסמך כדי שהעסקה תצליח. ההגדרה קובעת אם להשתמש בעסקאות N1QL כשמבצעים שאילתות.
transaction_timeout	מחרוזת	לא נכון	ההגדרה הזו קובעת את פרק הזמן שבו יכולה להתבצע עסקה לפני ש-Couchbase יפסיק אותה בגלל חריגה מזמן קצוב.
use_collections_for_ddl	בוליאני	לא נכון	האם להניח שהצהרות CREATE TABLE משתמשות בקולקציות במקום בטעמים. המדיניות הזו תקפה רק כשמתחברים ל-Couchbase גרסה 7 ומעלה, וההגדרה GenerateSchemaFiles מוגדרת ל-OnCreate.
use_transactions	מחרוזת	לא נכון	ההגדרה קובעת אם להשתמש בעסקאות N1QL כשמבצעים שאילתות.
validate_jsonparameters	בוליאני	לא נכון	מאפשר לספק לאמת שפרמטרים של מחרוזות הם JSON תקין לפני שליחת השאילתה ל-Couchbase.
proxy_enabled	בוליאני	לא נכון	מסמנים את תיבת הסימון הזו כדי להגדיר שרת Proxy לחיבור.
proxy_auth_scheme	ENUM	לא נכון	סוג האימות שבו יש להשתמש כדי לבצע אימות לשרת ה-proxy‏ ProxyServer. הערכים הנתמכים הם: BASIC, ‏ DIGEST, ‏ NONE
proxy_user	מחרוזת	לא נכון	שם משתמש שישמש לאימות בשרת ה-proxy ‏ProxyServer.
proxy_password	SECRET	לא נכון	סיסמה שתשמש לאימות בשרת ה-proxy‏ ProxyServer.
proxy_ssltype	ENUM	לא נכון	סוג ה-SSL שבו צריך להשתמש כשמתחברים לשרת ה-proxy של ProxyServer. הערכים הנתמכים הם: AUTO, ‏ ALWAYS, ‏ NEVER, ‏ TUNNEL
דרגת מלל	מחרוזת	לא נכון	רמת המלל של החיבור, משתנה מ-1 עד 5. רמת הפירוט הגבוהה יותר תתעד את כל פרטי התקשורת (בקשה,תגובה ואישורי SSL).

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

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

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

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

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

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

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