שימוש במנהל ההתקן של JDBC ל-BigQuery

מנהל ההתקן של Java Database Connectivity (JDBC)‎ ל-BigQuery מחבר את אפליקציות Java ל-BigQuery, ומאפשר לכם להשתמש בתכונות של BigQuery עם הכלים והתשתית המועדפים עליכם. כדי לחבר אפליקציות שאינן Java ל-BigQuery, השתמשו במנהל ההתקן של Open Database Connectivity (ODBC) ל-BigQuery.

מגבלות

מנהל ההתקן של JDBC ל-BigQuery כפוף למגבלות הבאות:

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

  1. חשוב לוודא שאתם מכירים את מנהלי ההתקנים של JDBC, את Apache Maven ואת החבילה java.sql.
  2. מוודאים שבמערכת מוגדרת סביבת זמן ריצה של Java‏ (JRE) בגרסה 8.0 ואילך. כדי לבדוק את גרסת ה-JRE, קראו את המאמר אימות סביבת ה-JRE.
  3. מאמתים את BigQuery, ושימו לב למידע הבא, שמשמש בהמשך ליצירת חיבור עם מנהל ההתקן של JDBC ל-BigQuery. אתם צריכים לשים לב רק למידע שמתאים לשיטת האימות שבה אתם משתמשים.

    שיטת אימות פרטי אימות דוגמה מאפיין החיבור (להגדרה בהמשך)
    חשבון שירות רגיל כתובת האימייל של חשבון השירות bq-jdbc-sa@mytestproject.s3ns.iam.gserviceaccount.com OAuthServiceAcctEmail
    מפתח לחשבון השירות (אובייקט JSON) my-sa-key OAuthPvtKey
    קובץ מפתח של חשבון שירות קובץ המפתח של חשבון השירות (נתיב מלא) path/to/file/secret.json OAuthPvtKeyPath
    חשבון משתמש ב-Google מזהה לקוח 123-abc.apps.googleusercontent.com OAuthClientId
    סוד לקוח _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    טוקן גישה שנוצר מראש טוקן גישה ya29.a0AfH6SMCiH1L-x_yZ OAuthAccessToken
    טוקן רענון שנוצר מראש טוקן רענון 1/fFAGRNJru1FTz70BzhT3Zg OAuthRefreshToken
    מזהה לקוח 123-abc.apps.googleusercontent.com OAuthClientId
    סוד לקוח _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Application Default Credentials ללא לא רלוונטי לא רלוונטי
    קובץ תצורה קובץ תצורה (אובייקט JSON או נתיב מלא) path/to/file/secret.json OAuthPvtKey
    אובייקט הגדרה של חשבון חיצוני אובייקט הגדרת החשבון external_account_configuration_object OAuthPvtKey
    אחר מאפיין הקהל של קובץ התצורה של החשבון החיצוני //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider BYOID_AudienceUri
    קובץ לאחזור טוקנים ומידע על הסביבה {\"file\":\"/path/to/file\"} BYOID_CredentialSource
    פרויקט של משתמש (רק אם משתמשים במאגר כוח עבודה) my_project BYOID_PoolUserProject
    ‫URI להתחזות לחשבון שירות (רק אם משתמשים במאגר של כוח עבודה) my-sa BYOID_SA_Impersonation_Uri
    אסימון של Security Token Service שמבוסס על המפרט של החלפת אסימונים urn:ietf:params:oauth:tokentype:id_token BYOID_SubjectTokenType
    נקודת הקצה להחלפת אסימונים של Security Token Service https://sts.googleapis.com/v1/token BYOID_TokenUri

התקנה והגדרה של מנהל ההתקן של JDBC

כדי להתקין ולהגדיר את מנהל ההתקן של JDBC ל-BigQuery, אתם יכולים להוריד ישירות את קובץ ה-uber-JAR או להשתמש ב-Maven.

הגדרת הורדה ישירה

כדי להגדיר את מנהל ההתקן של JDBC באמצעות הורדה ישירה:

  1. מורידים את גרסה 1.6.0 של מנהל ההתקן.
  2. מעתיקים את הקובץ שהורדתם למיקום שצוין בתוכנה.

למידע על שינויים בתכונות ועדכונים בתהליכי עבודה, קראו את יומן השינויים.

הגדרת Maven

מנהל ההתקן של JDBC ל-BigQuery זמין ב-Maven Central.

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

Maven

מוסיפים את התלות הבאה לקובץ pom.xml:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
</dependency>

‫Maven באמצעות uber-JAR

מוסיפים את התלות הבאה לקובץ pom.xml:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
    <classifier>all</classifier>
    <exclusions>
      <exclusion>
        <groupId>*</groupId>
        <artifactId>*</artifactId>
      </exclusion>
    </exclusions>
</dependency>

Gradle

מוסיפים לקובץ build.gradle את הנתונים הבאים:

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.6.0")
}

יצירת חיבור

כדי ליצור חיבור בין אפליקציית Java לבין BigQuery באמצעות מנהל ההתקן של JDBC ל-BigQuery:

  1. מזהים את מחרוזת החיבור של מנהל ההתקן של JDBC ל-BigQuery. המחרוזת הזו כוללת את כל המידע שנדרש כדי ליצור חיבור בין אפליקציית Java לבין BigQuery. מחרוזת החיבור היא בפורמט הבא:

    jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫HOST: כתובת ה-DNS או כתובת ה-IP של השרת.
    • ‫PORT: מספר היציאה של ה-TCP.
    • ‫PROJECT_ID: מזהה הפרויקט ב-BigQuery.
    • ‫AUTH_TYPE: מספר שמציין את סוג האימות שבו השתמשתם. אחד מהפרטים הבאים:
      • ‫0: לאימות של חשבון שירות (רגיל וקובץ מפתח)
      • ‫1: לאימות של חשבון משתמש ב-Google
      • ‫2: לאימות של טוקן גישה או טוקן רענון שנוצר מראש
      • ‫3: לאימות באמצעות Application Default Credentials
      • ‫4: לשיטות אימות אחרות
    • ‫AUTH_PROPS: פרטי האימות שציינתם כשאימתתם את BigQuery, בפורמט property_1=value_1; property_2=value_2;.... לדוגמה, OAuthPvtKeyPath=path/to/file/secret.json אם האימות בוצע באמצעות קובץ מפתח של חשבון שירות.
    • ‫OTHER_PROPS (אופציונלי): מאפייני חיבור נוספים למנהל ההתקן של JDBC, בפורמט property_1=value_1; property_2=value_2;.... לרשימה המלאה של מאפייני החיבור, ראו מאפייני החיבור.
  2. מחברים את אפליקציית Java למנהל ההתקן של JDBC ל-BigQuery באמצעות המחלקה DriverManager או DataSource.

    • התחברות לכיתה DriverManager:

      import java.sql.Connection;
      import java.sql.DriverManager;
      
      private static Connection getJdbcConnectionDM(){
        Connection connection = DriverManager.getConnection(CONNECTION_STRING);
        return connection;
      }

      מחליפים את CONNECTION_STRING במחרוזת החיבור מהשלב הקודם.

    • התחברות לכיתה DataSource:

      import com.google.cloud.bigquery.jdbc.DataSource;
      import java.sql.Connection;
      import java.sql.SQLException;
      
      private static public Connection getJdbcConnectionDS() throws SQLException {
        Connection connection = null;
        DataSource dataSource = new com.google.cloud.bigquery.jdbc.DataSource();
        dataSource.setURL(CONNECTION_STRING);
        connection = dataSource.getConnection();
        return connection;
      }

      מחליפים את CONNECTION_STRING במחרוזת החיבור מהשלב הקודם.

      במחלקה DataSource יש גם שיטות setter שאפשר להשתמש בהן כדי להגדיר מאפייני חיבור, במקום לכלול אותם במחרוזת החיבור. לדוגמה:

      private static Connection getConnection() throws SQLException {
        DataSource ds = new DataSource();
        ds.setURL(jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;);
        ds.setAuthType(3);  // Application Default Credentials
        ds.setProjectId("MyTestProject");
        ds.setEnableHighThroughputAPI(true);
        ds.setLogLevel("6");
        ds.setUseQueryCache(false);
        return ds.getConnection();
      }

מאפייני החיבור

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

מאפיין החיבור תיאור ערך ברירת המחדל סוג הנתונים חובה
AdditionalProjects פרויקטים שמנהל ההתקן יכול לגשת אליהם לצורך שאילתות ופעולות של מטא-נתונים, בנוסף לפרויקט הראשי שמוגדר על ידי המאפיין ProjectId. לא רלוונטי מחרוזת מופרדת בפסיקים לא
AllowLargeResults קובע אם מנהל ההתקן מעבד תוצאות שאילתה שגדולות מ-128MB כשהמאפיין QueryDialect מוגדר ל-BIG_QUERY. אם המאפיין QueryDialect מוגדר לערך SQL, מנהל ההתקן תמיד מעבד תוצאות של שאילתות גדולות. TRUE בוליאני לא
BYOID_AudienceUri המאפיין audience בקובץ תצורה של חשבון חיצוני. המאפיין audience יכול להכיל את שם המשאב של מאגר הזהויות של עומסי העבודה או של מאגר כוח העבודה, וגם את המזהה של הספק במאגר הזה. לא רלוונטי String רק כשOAuthType=4
BYOID_CredentialSource אחזור הטוקן ומידע על הסביבה. לא רלוונטי String רק כשOAuthType=4
BYOID_PoolUserProject הפרויקט של המשתמש כשמשתמשים במאגר כוח עבודה לאימות. לא רלוונטי String רק כש-OAuthType=4 ובשימוש במאגר כוח העבודה
BYOID_SA_Impersonation_Uri ה-URI להתחזות לחשבון שירות כשמשתמשים במאגר כוח עבודה לאימות. לא רלוונטי String רק כש-OAuthType=4 ובשימוש במאגר כוח העבודה
BYOID_SubjectTokenType האסימון של Security Token Service שמבוסס על מפרט החלפת האסימונים. אחד מהפרטים הבאים:
  • urn:ietf:params:oauth:token-type:jwt
  • urn:ietf:params:oauth:token-type:id_token
  • urn:ietf:params:oauth:token-type:saml2
  • urn:ietf:params:aws:token-type:aws4_request
urn:ietf:params:oauth:tokentype:id_token String רק כשOAuthType=4
BYOID_TokenUri נקודת הקצה להחלפת אסימונים של Security Token Service. https://sts.googleapis.com/v1/token String לא
ConnectionPoolSize גודל מאגר החיבורים, אם מאגר החיבורים מופעל. 10 ארוכה לא
DefaultDataset מערך הנתונים שמשמש כשלא מצוין מערך נתונים בשאילתה. לא רלוונטי String לא
EnableGcpLogExporter ההגדרה קובעת אם הדרייבר מייצא באופן אוטומטי יומנים ל-Cloud Logging (אם לא נעשה שימוש במכונה גלובלית או מותאמת אישית של OpenTelemetry). מידע נוסף זמין במאמר בנושא OpenTelemetry. FALSE בוליאני לא
EnableGcpTraceExporter ההגדרה הזו קובעת אם הדרייבר מייצא באופן אוטומטי את נתוני המעקב ל-Cloud Trace (אם לא משתמשים במכונה גלובלית או מותאמת אישית של OpenTelemetry). מידע נוסף זמין במאמר בנושא OpenTelemetry. FALSE בוליאני לא
EnableHighThroughputAPI קובעת אם אפשר להשתמש ב-Storage Read API. כדי להשתמש ב-Storage Read API, צריך להגדיר גם את המאפיינים HighThroughputActivationRatio ו-HighThroughputMinTableSize לערך TRUE. FALSE בוליאני לא
EnableProjectDiscovery ההגדרה קובעת אם שיטות המטא-נתונים של מסד הנתונים יגלו מערכי נתונים בכל הפרויקטים ב- Cloud de Confiance שיש אליהם גישה. כשהמדיניות מוגדרת לערך FALSE, הגילוי מוגבל לערך ברירת המחדל ProjectId. FALSE בוליאני לא
EnableSession קובע אם החיבור מתחיל סשן. אם הערך הוא TRUE, מזהה הסשן מועבר לכל השאילתות הבאות. FALSE בוליאני לא
EnableTimestampPicos ההגדרה קובעת אם מנהל ההתקן מאחזר ערכי TIMESTAMP(12) ברמת דיוק של פיקו-שנייה. כשהערך מוגדר כ-TRUE, ערכי TIMESTAMP(12) מוחזרים כאובייקטים של String בפורמט UTC על ידי השיטות getString() ו-getObject(). כשמגדירים את הערך FALSE, ערכי TIMESTAMP(12) נחתכים לדיוק של 6 ספרות במיקרו-שניות. המאפיין הזה לא תואם ל-SQL מדור קודם (QueryDialect=BIG_QUERY). FALSE בוליאני לא
EnableWriteAPI ההגדרה קובעת אם אפשר להשתמש ב-Storage Write API ‏ (gRPC). כדי לאפשר הוספה בכמות גדולה, צריך להגדיר אותו לערך TRUE. FALSE בוליאני לא
EndpointOverrides נקודות קצה (endpoints) בהתאמה אישית כדי לשנות את:
  • BIGQUERY=https://bigquery.googleapis.com
  • READ_API=https://bigquerystorage.googleapis.com
  • OAUTH2=https://oauth2.googleapis.com
  • STS=https://sts.googleapis.com
לא רלוונטי מחרוזת מופרדת בפסיקים לא
FilterTablesOnDefaultDataset קובע את היקף המטא-נתונים שמוחזרים על ידי השיטות DatabaseMetaData.getTables() ו-DatabaseMetaData.getColumns(). כשהמדיניות מוגדרת לערך FALSE, לא מתבצע סינון. כדי להפעיל את הסינון, צריך להגדיר גם את המאפיין DefaultDataset. FALSE בוליאני לא
GcpTelemetryCredentials פרטי הכניסה שמשמשים לאימות של מייצאים של נתוני טלמטריה. מקבל נתיב למפתח JSON של חשבון שירות או למחרוזת JSON גולמית. אם לא מגדירים את הפרמטר, ברירת המחדל היא פרטי הכניסה של החיבור. מידע נוסף זמין במאמר OpenTelemetry. לא רלוונטי String לא
GcpTelemetryProjectId מזהה הפרויקט ב- Cloud de Confiance by S3NS שאליו נשלחים נתוני הטלמטריה. ברירת המחדל היא ProjectId הראשי. מידע נוסף זמין במאמר OpenTelemetry. לא רלוונטי String לא
HighThroughputActivationRatio הסף למספר הדפים בתגובה לשאילתה. אם חורגים מהמספר הזה, ומתקיימים התנאים של EnableHighThroughputAPI ו-HighThroughputMinTableSize, הדרייבר מתחיל להשתמש ב-Storage Read API. 2 מספר שלם לא
HighThroughputMinTableSize הסף למספר השורות בתגובה לשאילתה. אם חורגים מהמספר הזה, ומתקיימים התנאים של EnableHighThroughputAPI ו-HighThroughputActivationRatio, הדרייבר מתחיל להשתמש ב-Storage Read API. 10000 מספר שלם לא
JobCreationMode קובע אם השאילתות יופעלו עם או בלי משימות. הערך 1 מציין שנוצרות משימות לכל שאילתה, והערך 2 מציין שאפשר להריץ שאילתות בלי משימות. 2 מספר שלם לא
JobTimeout הזמן הקצוב לתפוגה של המשימה (בשניות), שאחריו המשימה מבוטלת בשרת. 0 ארוכה לא
KMSKeyName שם המפתח ב-KMS להצפנת נתונים. לא רלוונטי String לא
Labels תוויות שמשויכות לשאילתה כדי לארגן ולקבץ משימות של שאילתות. לא רלוונטי <String, String> מפה לא
LargeResultDataset מערך הנתונים של היעד לתוצאות של שאילתות גדולות, רק כשהמאפיין LargeResultTable מוגדר. כשמגדירים את המאפיין הזה, כתיבת הנתונים עוקפת את המטמון של התוצאות ומפעילה חיוב לכל שאילתה, גם אם התוצאות קטנות. _google_jdbc String לא
LargeResultsDatasetExpirationTime משך החיים של כל הטבלאות במערך נתונים גדול של תוצאות, באלפיות השנייה. המערכת מתעלמת מהמאפיין הזה אם כבר מוגדר זמן תפוגה כברירת מחדל לקבוצת הנתונים. 3600000 ארוכה לא
LargeResultTable טבלת היעד לתוצאות של שאילתות גדולות, רק כשהמאפיין LargeResultDataset מוגדר. כשמגדירים את המאפיין הזה, כתיבת הנתונים עוקפת את המטמון של התוצאות ומפעילה חיוב לכל שאילתה, גם אם התוצאות קטנות. temp_table... String לא
ListenerPoolSize גודל מאגר המאזינים, אם מאגר החיבורים מופעל. 10 ארוכה לא
Location המיקום שבו נוצרים מערכי הנתונים או שבו מתבצעות השאילתות. אם המאפיין הזה לא מוגדר, המיקום נקבע באופן אוטומטי על ידי BigQuery. לא רלוונטי String לא
LogLevel רמת הפירוט של הרישום ביומן על ידי מנהל ההתקן. מידע נוסף זמין במאמר רישום ביומן. 0 מספר שלם לא
LogPath הספרייה שבה נכתבים קובצי היומן. לא רלוונטי String לא
MaximumBytesBilled מגבלת הבייטים לחיוב. שאילתות עם מספר בייטים לחיוב שגבוה מהמספר הזה ייכשלו בלי שהחשבון יחויב. 0 ארוכה לא
MaxResults המספר המקסימלי של תוצאות בכל דף. 10000 ארוכה לא
MetaDataFetchThreadCount מספר השרשורים שמשמשים לשיטות של מטא-נתונים של מסד נתונים. 32 מספר שלם לא
OAuthAccessToken טוקן הגישה שמשמש לאימות של טוקן גישה שנוצר מראש. לא רלוונטי String רק כשOAUTH_TYPE=2
OAuthClientId מזהה הלקוח לאימות של טוקן רענון שנוצר מראש ולאימות של חשבון המשתמש. לא רלוונטי String רק כש-OAUTH_TYPE=1 או OAUTH_TYPE=2
OAuthClientSecret סוד הלקוח לאימות של טוקן רענון שנוצר מראש ולאימות של חשבון משתמש. לא רלוונטי String רק כש-OAUTH_TYPE=1 או OAUTH_TYPE=2
OAuthP12Password הסיסמה לקובץ המפתח PKCS12. notasecret String לא
OAuthPvtKey המפתח של חשבון השירות כשמשתמשים באימות של חשבון שירות. הערך הזה יכול להיות אובייקט גולמי של קובץ מפתח JSON או נתיב לקובץ מפתח JSON. לא רלוונטי String רק כשהערך של OAUTH_TYPE=0 ושל OAuthPvtKeyPath לא מוגדר
OAuthPvtKeyPath הנתיב למפתח של חשבון השירות כשמשתמשים באימות של חשבון שירות. לא רלוונטי String רק כש-OAUTH_TYPE=0 והערכים של OAuthPvtKey ו-OAuthServiceAcctEmail לא מוגדרים
OAuthRefreshToken טוקן הרענון לאימות באמצעות טוקן רענון שנוצר מראש. לא רלוונטי String רק כשOAUTH_TYPE=2
OAuthServiceAcctEmail כתובת האימייל של חשבון השירות, כשמשתמשים באימות של חשבון שירות. לא רלוונטי String רק כשהערך של OAUTH_TYPE=0 ושל OAuthPvtKeyPath לא מוגדר
OAuthType סוג האימות. אחד מהפרטים הבאים:
  • ‫0: אימות של חשבון שירות
  • ‫1: אימות של חשבון המשתמש
  • 2: אימות באמצעות טוקן גישה או טוקן רענון שנוצר מראש
  • ‫3: אימות באמצעות Application Default Credentials
  • ‫4: שיטות אימות אחרות
-1 מספר שלם כן
PartnerToken אסימון שמשמש את השותפים של Cloud de Confiance כדי לעקוב אחרי השימוש במנהל ההתקן. לא רלוונטי String לא
ProjectId מזהה הפרויקט שמוגדר כברירת מחדל לדרייבר. הפרויקט הזה משמש להרצת שאילתות, והחיוב בו הוא על השימוש במשאבים. אם לא מגדירים את המאפיין, מזהה הפרויקט מוסק על ידי הדרייבר. לא רלוונטי String לא, אבל מומלץ מאוד
ProxyHost שם המארח או כתובת ה-IP של שרת proxy שדרכו מנותב חיבור ה-JDBC. לא רלוונטי String לא
ProxyPort מספר היציאה שבה שרת ה-proxy מאזין לחיבורים. לא רלוונטי String לא
ProxyPwd הסיסמה לאימות כשמתחברים דרך שרת proxy שדורש את זה. לא רלוונטי String לא
ProxyUid שם המשתמש לאימות כשמתחברים דרך שרת proxy שדורש את זה. לא רלוונטי String לא
QueryDialect ניב ה-SQL להרצת השאילתה. משתמשים ב-SQL ל-GoogleSQL (מומלץ מאוד) וב-BIG_QUERY ל-SQL מדור קודם. SQL String לא
QueryProperties מאפייני חיבור REST שמתאימים אישית את אופן הפעולה של השאילתה. לא רלוונטי <String, String> מפה לא
RequestGoogleDriveScope הוספת היקף הרשאות לקריאה בלבד ב-Drive לחיבור, כשהערך מוגדר כ-1. 0 מספר שלם לא
RetryInitialDelay הגדרת ההשהיה (בשניות) לפני הניסיון החוזר הראשון. 0 ארוכה לא
RetryMaxDelay מגדירה את המגבלה המקסימלית (בשניות) להשהיה של הניסיון החוזר. 0 ארוכה לא
ServiceAccountImpersonationChain רשימה מופרדת בפסיקים של כתובות אימייל של חשבונות שירות בשרשרת ההתחזות. לא רלוונטי String לא
ServiceAccountImpersonationEmail כתובת האימייל של חשבון השירות שמתחזים אליו. לא רלוונטי String לא
ServiceAccountImpersonationScopes רשימה מופרדת בפסיקים של היקפי OAuth 2.0 לשימוש עם החשבון המתחזה. https://www.googleapis.com/auth/bigquery String לא
ServiceAccountImpersonationTokenLifetime משך החיים של האסימון של החשבון שבוצעה אליו התחזות (בשניות). 3600 מספר שלם לא
SSLTrustStore הנתיב המלא ל-Java TrustStore שמכיל אישורים של רשות אישורים (CA) מהימנה. מנהל ההתקן משתמש במאגר האישורים הזה כדי לאמת את זהות השרת במהלך לחיצת היד בפרוטוקול SSL/TLS. לא רלוונטי String לא
SSLTrustStoreProvider ספק Java Cryptography Extension ‏ (JCE) שמשמש למאפיין SSLTrustStore. לא רלוונטי String לא
SSLTrustStorePwd הסיסמה ל-Java TrustStore שצוינה במאפיין SSLTrustStore. לא רלוונטי String רק אם ה-Java TrustStore מוגן בסיסמה
SSLTrustStoreType הפורמט של קובץ ה-truststore שצוין במאפיין SSLTrustStore (למשל JKS,‏ PKCS12 או ROTKS). לא רלוונטי String לא
SWA_ActivationRowCount הסף של executeBatch insert שורות, שאם חורגים ממנו, המחבר עובר ל-Storage Write API ‏ (gRPC). 3 מספר שלם לא
SWA_AppendRowCount גודל ה-write stream. 1000 מספר שלם לא
Timeout משך הזמן, בשניות, שבו המחבר מנסה שוב לבצע קריאה ל-API שנכשלה לפני שנגמר הזמן הקצוב לתפוגה. 0 ארוכה לא
UniverseDomain הדומיין ברמה העליונה שמשויך למשאבי Cloud de Confiance של הארגון. googleapis.com String לא
UnsupportedHTAPIFallback ההגדרה קובעת אם המחבר חוזר ל-API בארכיטקטורת REST (כשהיא מוגדרת ל-TRUE) או מחזיר שגיאה (כשהיא מוגדרת ל-FALSE). TRUE בוליאני לא
UseGlobalOpenTelemetry ההגדרה קובעת אם הדרייבר משתמש ב-GlobalOpenTelemetry.get() למדידה. מידע נוסף זמין במאמר OpenTelemetry. FALSE בוליאני לא
UseQueryCache הפעלת שמירת שאילתות במטמון. TRUE בוליאני לא

הרצת שאילתות באמצעות הדרייבר

אחרי שמחברים את אפליקציית Java ל-BigQuery באמצעות מנהל ההתקן של JDBC, אפשר להריץ שאילתות בסביבת הפיתוח באמצעות תהליך JDBC הרגיל. כל המכסות והמגבלות של BigQuery חלות.

מיפוי סוגי נתונים

כשמריצים שאילתות באמצעות מנהל ההתקן של JDBC ל-BigQuery, מתבצע מיפוי של סוגי הנתונים הבאים:

סוג GoogleSQL סוג Java
ARRAY Array
BIGNUMERIC BigDecimal
BOOL Boolean
BYTES byte[]
DATE Date
DATETIME String
FLOAT64 Double
GEOGRAPHY String
INT64 Long
INTERVAL String
JSON String
NUMERIC BigDecimal
STRING String
STRUCT Struct
TIME Time
TIMESTAMP Timestamp

דוגמאות

בקטעים הבאים מופיעות דוגמאות לשימוש בתכונות של BigQuery באמצעות מנהל ההתקן של JDBC ל-BigQuery.

פרמטרים תלויי מיקום

בדוגמה הבאה מריצים שאילתה עם פרמטר מיקום:

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

רשומות בתוך רשומות ורשומות חוזרות

השאילתה הבאה לדוגמה שולפת את רשומת הבסיס של נתוני Struct:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct obj = (Struct) resultSet.getObject(1);
    System.out.println(obj.toString());

הדרייבר מחזיר את רשומת הבסיס כאובייקט struct או כמחרוזת שמייצגת אובייקט JSON. התוצאה אמורה להיראות כך:

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

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

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct structObject = (Struct) resultSet.getObject(1);
    Object[] structComponents = structObject.getAttributes();
    for (Object component : structComponents){
      System.out.println(component.toString());
    }

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

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT [1,2,3]");
resultSet.next();
Object[] arrayObject = (Object[]) resultSet.getArray(1).getArray();

// Verify Result
int count =0;
for (; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

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

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT "
    + "[STRUCT(\"Adam\" as name, 12 as age), "
    + "STRUCT(\"Lily\" as name, 17 as age)]");

Struct[] arrayObject = (Struct[]) resultSet.getArray(1).getArray();

// Verify Result
for (int count =0; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

הוספה בכמות גדולה

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

Connection conn = DriverManager.getConnection(connectionUrl);
PreparedStatement statement = null;
Statement st = conn.createStatement();
final String insertQuery = String.format(
        "INSERT INTO `%s.%s.%s` "
      + " (StringField, IntegerField, BooleanField) VALUES(?, ?, ?);",
        DEFAULT_CATALOG, DATASET, TABLE_NAME);

statement = conn.prepareStatement(insertQuery1);

for (int i=0; i<2000; ++i) {
      statement.setString(1, i+"StringField");
      statement.setInt(2, i);
      statement.setBoolean(3, true);
      statement.addBatch();
}

statement.executeBatch();

רישום ביומן

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

רמות הרישום ביומן

המאפיין LogLevel קובע את רמת הפירוט של הרישום ביומן בחבילה java.util.logging:

  • ‫0: OFF (ברירת מחדל)
  • 1: SEVERE
  • 2: ‏WARNING
  • 3: ‏INFO
  • 4: ‏CONFIG
  • 5: ‏FINE
  • 6: ‏FINER
  • 7: ‏FINEST
  • 8: ALL

אנחנו ממליצים על רמה 6 לפתרון בעיות כלליות. רמות 7 ו-8 מוגבלות לפעולות של ResultSet ויוצרות נפח גדול של יומנים.

הפעלת רישום ביומן במחרוזת החיבור

כדי להפעיל את הרישום ביומן במחרוזת החיבור, מוסיפים את מאפייני החיבור LogLevel ו-LogPath, לדוגמה:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=MyTestProject;OAuthType=3;LogLevel=6;LogPath=/tmp/jdbc-logs;

הפעלת רישום ביומן באמצעות משתני סביבה

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

  • ‫BIGQUERY_JDBC_LOG_LEVEL: רמת הרישום ביומן (0-8).
  • ‫BIGQUERY_JDBC_LOG_PATH: הספרייה של קובצי היומן.

לדוגמה, בסביבה של Linux או macOS, מריצים את הפקודה הבאה:

export BIGQUERY_JDBC_LOG_LEVEL=6
export BIGQUERY_JDBC_LOG_PATH=/tmp/jdbc-logs

OpenTelemetry

מנהל ההתקן של JDBC ל-BigQuery תומך ב-OpenTelemetry‏ (OTel) כדי לספק מעקב ורישום ביומן מבוזרים, שמאפשרים לעקוב אחרי הביצועים של האינטראקציות עם מסד הנתונים ולפתור בעיות ביעילות.

פעולות במעקב

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

  • הרצת שאילתה: נוצרים טווחים ל-BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) ול-BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
  • פעולות של מטא-נתונים: טווחי זמן נוצרים לשיטות ספציפיות של DatabaseMetaData (getCatalogs(), ‏ getSchemas(), ‏ getTables(), ‏ getColumns()).
  • עימוד: אחזורים אסינכרוניים של דפי תוצאות נוספים (כשמשתמשים בנתיב של ה-API בארכיטקטורת REST) עוברים מעקב ומקושרים באופן סיבתי לטווח הביצוע של השאילתה המקורית באמצעות קישורי טווח של OpenTelemetry. לפעולות האלה נוצר span בשם BigQueryStatement.pagination.
  • הפצת הקשר: מנהל ההתקן של JDBC מפיץ את ההקשר הפעיל ל-SDK הבסיסי של google-cloud-bigquery. כתוצאה מכך, טווחי זמן שנוצרו על ידי ה-SDK (כמו קריאות HTTP RPC) מופיעים באופן אוטומטי כצאצאים של טווחי הזמן של JDBC, ומספקים היררכיית מעקב מלאה מקצה לקצה.

מצבי הגדרה

אתם יכולים להגדיר את OpenTelemetry במנהל ההתקן של JDBC באחד מהמצבים הבאים, בהתאם לארכיטקטורה ולדרישות של האפליקציה.

טלמטריה שמנוהלת על ידי האפליקציה

אם האפליקציה כבר משתמשת ב-OpenTelemetry, אתם יכולים להחדיר את המכונה של OpenTelemetry למנהל ההתקן של JDBC כדי לוודא שהנתונים של מנהל ההתקן תואמים לנתונים של האפליקציה.

כדי לעשות את זה, משתמשים ב-API של BigQueryDataSource:

BigQueryDataSource dataSource = new BigQueryDataSource();
// ... set other properties ...
dataSource.setCustomOpenTelemetry(yourOpenTelemetryInstance);

תמיכה גלובלית ב-OpenTelemetry

אם הפעלתם את OpenTelemetry באופן גלובלי באפליקציה (לדוגמה, באמצעות OpenTelemetry Java Agent או באמצעות קריאה לפונקציה GlobalOpenTelemetry.set()), אתם יכולים להגדיר את הדרייבר כך שישתמש במכונה הגלובלית הזו.

כדי להפעיל את המכונה הגלובלית, מגדירים את מאפיין החיבור UseGlobalOpenTelemetry לערך TRUE.

טלמטריה Cloud de Confiance ללא הגדרות אישיות

אם אתם משתמשים ב- Cloud de Confiance ורוצים הגדרה מהירה, אתם יכולים להפעיל ייצוא אוטומטי של נתוני מעקב ויומנים לניטור של Cloud de Confiance (מעקב ורישום ביומן).

כדי להפעיל את הייצוא הזה, צריך להגדיר את מאפייני החיבור הבאים בכתובת ה-URL של JDBC:

  • EnableGcpTraceExporter=true
  • EnableGcpLogExporter=true

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

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=your-project-id;EnableGcpTraceExporter=true;EnableGcpLogExporter=true;

מאפייני החיבור של OpenTelemetry

מאפייני החיבור הבאים נתמכים ב-OpenTelemetry. במאמר מאפייני חיבור תוכלו לקרוא תיאורים מפורטים וערכי ברירת מחדל.

  • EnableGcpLogExporter
  • EnableGcpTraceExporter
  • GcpTelemetryCredentials
  • GcpTelemetryProjectId
  • UseGlobalOpenTelemetry

שיקולים חשובים

כשפורסים את השילוב של OpenTelemetry, חשוב להביא בחשבון את השיקולים הבאים לגבי התנהגות הרישום ביומן, האימות, הגדרת שרת ה-proxy והתמחור.

אינטראקציה עם LogLevel

מאפיין החיבור הקיים LogLevel משמש כשומר הסף הראשי לרישום ביומן.

  • אם מוגדר הערך LogLevel=0 (כבוי), לא נוצרים רשומות ביומן. לכן, לא מיוצאים יומנים באמצעות OpenTelemetry או ל-Logging, גם אם EnableGcpLogExporter=true.
  • כדי להפעיל את הרישום ביומן של OTel, צריך לוודא שהערך של LogLevel גדול מ-0 (לדוגמה, 5 ליומנים מפורטים).

אימות לטלמטריה

ייצוא נתוני הטלמטריה (גם מעקב וגם רישום ביומן) עם החלופה האוטומטית שלCloud de Confiance תומך גם ב-Application Default Credentials ‏(ADC) וגם בפרטי כניסה מפורשים של חשבון שירות שסופקו באמצעות GcpTelemetryCredentials.

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

הגדרת שרת Proxy עם OpenTelemetry ורישום ביומן

אם האפליקציה מתחברת ל-BigQuery דרך שרת proxy, מנהל ההתקן מטפל בניתוב של ה-proxy באופן הבא:

  • ייצוא של נתוני מעקב (HTTP). כשמשתמשים בפרוטוקול ברירת המחדל של HTTP לייצוא של נתוני מעקב ב-OpenTelemetry‏ (otel.exporter.otlp.protocol=http/protobuf), הדרייבר מנתב באופן אוטומטי את תנועת הייצוא של נתוני המעקב דרך שרת ה-proxy שמוגדר במאפייני החיבור באמצעות ProxyHost ו-ProxyPort.
  • ייצוא יומנים וטלמטריית gRPC. מייצא היומנים האוטומטי של Cloud de Confiance (EnableGcpLogExporter=true) ומייצאי OpenTelemetry שמבוססים על gRPC (otel.exporter.otlp.protocol=grpc) משתמשים ב-gRPC, שלא תומך בהגדרת שרת proxy לכל חיבור. כדי לנתב את תעבורת הנתונים של ייצוא היומנים ושל הטלמטריה של gRPC דרך שרת proxy, צריך להגדיר את הגדרות לשרת proxy ברמת ה-JVM באמצעות מאפייני המערכת הבאים:

    -Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT

ממשקי ה-API והרשאות ה-IAM הנדרשים

כדי לכתוב נתוני טלמטריה ל- Cloud de Confiance by S3NS observability, צריך לבצע את ההגדרה הבאה בפרויקט היעד ב- Cloud de Confiance :

  1. מפעילים את ממשקי ה-API:
    • מפעילים את Cloud Trace API ‏ (cloudtrace.googleapis.com).
    • מפעילים את Cloud Logging API ‏ (logging.googleapis.com).
  2. הקצאת תפקידי IAM:
    • לייצוא של נתוני מעקב: מקצים לחשבון המשתמש או לחשבון השירות את התפקיד "סוכן Trace"‏ (roles/cloudtrace.agent).
    • לייצוא יומנים: מקצים לחשבון המשתמש או לחשבון השירות את התפקיד "כתיבה ביומנים" (roles/logging.logWriter).

תמחור וחיוב

כשמשתמשים בטלמטריה ללא הגדרה Cloud de Confiance (EnableGcpTraceExporter=true או EnableGcpLogExporter=true), נתוני הטלמטריה נשלחים ל-Trace ול-Logging. יכול להיות שתחויבו על השירותים האלה בהתאם לנפח הנתונים שנקלטו. מידע נוסף זמין במאמר Google Cloud Observability.

מדדים

השילוב הזה לא תומך במדדי OpenTelemetry.

הצללת תלות

כדי למנוע התנגשויות של classpath עם האפליקציה, הדרייבר מסתיר את יחסי התלות של OpenTelemetry SDK ושל המייצא. ‫OpenTelemetry API נשאר לא מוצלל כדי לאפשר יכולת פעולה הדדית עם ה-SDK שסופק על ידי האפליקציה.

קורלציה בין רישום ביומן למעקב

כשהאפשרות OpenTelemetry מופעלת, מנהל ההתקן מקשר באופן אוטומטי בין היומנים לבין המעקבים:

  • ‫db.connection_id: מצורף כמאפיין span לכל ה-spans של JDBC.
  • ‫jdbc.connection_id: משמש כמפתח מטען ומצורף כתווית לכל רשומות היומן שהדרייבר שולח ל-Logging.
  • מזהה מעקב ומזהה טווח: יומנים שנוצרים במסגרת של הרצת שאילתה כוללים באופן אוטומטי את trace_id ו-span_id הפעילים.

תמחור

אתם יכולים להוריד את מנהל ההתקן של JDBC ל-BigQuery בחינם. עם זאת, כשמשתמשים במנהל ההתקן, חל התמחור הרגיל של BigQuery.

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