שימוש בלקוח Cassandra Java כדי להתחבר ל-Spanner Omni

תצוגה מקדימה

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

‫Cassandra Java client for Spanner מקשר בין אפליקציות שנכתבו עבור מסד הנתונים של Apache Cassandra לבין Spanner. הלקוח עובד עם Spanner Omni באותו אופן שבו הוא עובד עם Spanner.

מכיוון ש-Spanner תומך באופן מקורי בפרוטוקול Cassandra v4 wire, לקוח Spanner Cassandra Java מתרגם את פרוטוקול Cassandra wire ל-Spanner gRPC API. כך תוכלו להעביר את אפליקציות Cassandra ל-Spanner עם שינויים מינימליים בקוד.

במאמר הזה מוסבר איך לשלב את הלקוח עם Spanner Omni באחת מהשיטות הבאות:

• תלות בתהליך: משתמשים בשיטה הזו באפליקציות Java שכבר משתמשות ב-cassandra-java-driver. הגישה הזו מטמיעה את הלקוח בתהליך האפליקציה כדי לבצע שינויים מינימליים בקוד.

• ‫קובץ עזר חיצוני: משתמשים בשיטה הזו באפליקציות שאינן Java או כשמשתמשים בכלים חיצוניים של Cassandra, כמו cqlsh. בגישה הזו, הלקוח פועל כתהליך עצמאי.

מידע נוסף מופיע במאמר בנושא ממשק Cassandra במסמכי התיעוד של Spanner.

מתי כדאי להשתמש בלקוח Spanner Cassandra Java

הלקוח הזה שימושי בתרחישים הבאים:

• שימוש ב-Spanner עם מינימום שינויים בקוד. אתם רוצים להשתמש ב-Spanner כקצה העורפי של אפליקציית Java, אבל מעדיפים להמשיך להשתמש ב-API המוכר של cassandra-java-driver כדי לגשת לנתונים.

• משתמשים בכלים של Cassandra שאינם Java. אתם רוצים להתחבר ל-Spanner באמצעות כלים סטנדרטיים של Cassandra כמו cqlsh או אפליקציות שנכתבו בשפות אחרות שמשתמשות במנהלי התקנים של Cassandra.

שימוש בלקוח כתלות בתהליך

השיטה המומלצת לחיבור אפליקציות Java ל-Spanner Omni היא שילוב של לקוח Spanner Cassandra Java כתלות בתהליך. בהשוואה לשיטת ה-sidecar proxy, ההגדרה בתוך התהליך מספקת ביצועים טובים יותר כי היא מונעת קפיצה נוספת ברשת ואת הסדרות והביטולים של הסדרות של הנתונים שקשורים לכך. בנוסף, היא מפשטת את ארכיטקטורת הפריסה כי לא צריך לנהל תהליך נפרד ועצמאי.

כדי להשתמש בלקוח כתלות בתהליך:

1. משנים את קוד היצירה של CqlSession ומוסיפים את האפשרויות הספציפיות לתקשורת עם Spanner Omni.

2. מוסיפים את לקוח Java של Spanner Cassandra כתלות לפרויקט.

   תקשורת בטקסט פשוט

   בדוגמה הבאה מוצג איך ליצור חיבור בטקסט פשוט ל-Spanner Omni:

   CqlSession session =
       SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
           .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
           .withConfigLoader(
               DriverConfigLoader.programmaticBuilder()
                   .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                   .withDuration(
                       DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                       Duration.ofSeconds(5))
                   .build())
       .setExperimentalHostEndpoint("ENDPOINT")
     .setUsePlainText(true)
           .build();
   
   // Rest of your business logic such as session.Query(SELECT * FROM ...)
   
   session.close();
   

   חיבור TLS

   כדי להשתמש בחיבור TLS, צריך לוודא שאישור ה-CA נוסף למאגר האישורים (truststore) שבו האפליקציה משתמשת, כמו שמתואר בהוראות ה-TLS של Java SDK:

   CqlSession session =
       SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
           .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
           .withConfigLoader(
               DriverConfigLoader.programmaticBuilder()
                   .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                   .withDuration(
                       DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                       Duration.ofSeconds(5))
                   .build())
       .setExperimentalHostEndpoint("ENDPOINT")
     .setUsePlainText(false)
           .build();
   
   // Rest of your business logic such as session.Query(SELECT * FROM ...)
   
   session.close();
   

   חיבור mTLS

   כדי להשתמש בחיבור mTLS, צריך לוודא שאישור ה-CA נוסף למאגר האישורים שבו האפליקציה משתמשת, ושמפתח הלקוח הוא בפורמט PKCS#8, כמו שמוסבר בהוראות ל-mTLS ב-Java SDK:

   CqlSession session =
       SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
           .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
           .withConfigLoader(
               DriverConfigLoader.programmaticBuilder()
                   .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                   .withDuration(
                       DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                       Duration.ofSeconds(5))
                   .build())
       .setExperimentalHostEndpoint("ENDPOINT")
     .setUsePlainText(false)
     .useClientCert("PATH_TO_CLIENT_CERT",
             "PATH_TO_CLIENT_KEY_PKCS8")
   
           .build();
   
   // Rest of your business logic such as session.Query(SELECT * FROM ...)
   
   session.close();
   

קובץ עזר חיצוני או תהליך עצמאי

פריסת לקוח Java של Spanner Cassandra כקובץ עזר חיצוני היא אפשרות יעילה לאפליקציות ולכלים שאינם Java, כמו cqlsh, להתחבר ל-Spanner Omni באמצעות דרייברים סטנדרטיים של Cassandra. בשיטה הזו, הלקוח מופעל כשרת proxy עצמאי של TCP שמיירט את תעבורת הנתונים של פרוטוקול Cassandra וממיר אותה ל-gRPC לצורך תקשורת עם Spanner Omni.

אפשר להריץ את קובץ העזר החיצוני באמצעות קובץ תצורה YAML או על ידי ציון מאפייני מערכת.

שימוש בקובץ הגדרות YAML

להגדרות של סביבת ייצור, מומלץ להשתמש בקובץ YAML כדי להגדיר את המתאם. השיטה הזו תומכת בכמה מאזינים ובהגדרות גלובליות:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

דוגמה config.yaml:

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  experimentalHostEndpoint: "ENDPOINT"
  clientCertPath: "PATH_TO_CLIENT_CERT"
  clientKeyPath: "PATH_TO_CLIENT_KEY_PKCS8"
  usePlainText: "false"

listeners:
  - name: "listener_1"
    host: "127.0.0.1"
    port: 9042
    spanner:
      databaseUri: "DATABASE_ID"
      numGrpcChannels: 4
      maxCommitDelayMillis: 5
  - name: "listener_2"
    host: "127.0.0.2"
    port: 9043
    spanner:
      databaseUri: "DATABASE_ID_2"
      numGrpcChannels: 8

שימוש במאפייני מערכת

אם יש לכם מאזין יחיד או פריסות פשוטות יותר, אתם יכולים להריץ את שרת ה-Proxy של ה-sidecar כתהליך עצמאי ולהגדיר את ההגדרות שלו באמצעות מאפייני מערכת של Java.

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

תקשורת בטקסט פשוט

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

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

חיבור TLS

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

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-jar PATH_TO_ADAPTER_JAR

חיבור mTLS

לחיבור mTLS, מריצים את הפקודה הבאה:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DclientCertPath=PATH_TO_CLIENT_CERT \
-DclientKeyPath=PATH_TO_CLIENT_KEY_PKCS8 \
-jar PATH_TO_ADAPTER_JAR