שימוש במנהל ההתקן של JDBC ל-BigQuery
מנהל ההתקן של Java Database Connectivity (JDBC) ל-BigQuery מחבר את אפליקציות Java ל-BigQuery, ומאפשר לכם להשתמש בתכונות של BigQuery עם הכלים והתשתית המועדפים עליכם. כדי לחבר אפליקציות שאינן Java ל-BigQuery, השתמשו במנהל ההתקן של Open Database Connectivity (ODBC) ל-BigQuery.
מגבלות
מנהל ההתקן של JDBC ל-BigQuery כפוף למגבלות הבאות:
- הדרייבר ספציפי ל-BigQuery ואי אפשר להשתמש בו עם מוצרים או שירותים אחרים.
- סוג הנתונים
INTERVALלא נתמך ב-BigQuery Storage Read API. - כל המגבלות של שפת הטיפול בנתונים (DML) חלות.
לפני שמתחילים
- חשוב לוודא שאתם מכירים את מנהלי ההתקנים של JDBC, את Apache Maven ואת החבילה
java.sql. - מוודאים שבמערכת מוגדרת סביבת זמן ריצה של Java (JRE) בגרסה 8.0 ואילך. כדי לבדוק את גרסת ה-JRE, קראו את המאמר אימות סביבת ה-JRE.
מאמתים את BigQuery, ושימו לב למידע הבא, שמשמש בהמשך ליצירת חיבור עם מנהל ההתקן של JDBC ל-BigQuery. אתם צריכים לשים לב רק למידע שמתאים לשיטת האימות שבה אתם משתמשים.
שיטת אימות פרטי אימות דוגמה מאפיין החיבור (להגדרה בהמשך) חשבון שירות רגיל כתובת האימייל של חשבון השירות bq-jdbc-sa@mytestproject.s3ns.iam.gserviceaccount.comOAuthServiceAcctEmailמפתח לחשבון השירות (אובייקט JSON) my-sa-keyOAuthPvtKeyקובץ מפתח של חשבון שירות קובץ המפתח של חשבון השירות (נתיב מלא) path/to/file/secret.jsonOAuthPvtKeyPathחשבון משתמש ב-Google מזהה לקוח 123-abc.apps.googleusercontent.comOAuthClientIdסוד לקוח _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uVOAuthClientSecretטוקן גישה שנוצר מראש טוקן גישה ya29.a0AfH6SMCiH1L-x_yZOAuthAccessTokenטוקן רענון שנוצר מראש טוקן רענון 1/fFAGRNJru1FTz70BzhT3ZgOAuthRefreshTokenמזהה לקוח 123-abc.apps.googleusercontent.comOAuthClientIdסוד לקוח _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uVOAuthClientSecretApplication Default Credentials ללא לא רלוונטי לא רלוונטי קובץ תצורה קובץ תצורה (אובייקט JSON או נתיב מלא) path/to/file/secret.jsonOAuthPvtKeyאובייקט הגדרה של חשבון חיצוני אובייקט הגדרת החשבון external_account_configuration_objectOAuthPvtKeyאחר מאפיין הקהל של קובץ התצורה של החשבון החיצוני //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-providerBYOID_AudienceUriקובץ לאחזור טוקנים ומידע על הסביבה {\"file\":\"/path/to/file\"}BYOID_CredentialSourceפרויקט של משתמש (רק אם משתמשים במאגר כוח עבודה) my_projectBYOID_PoolUserProjectURI להתחזות לחשבון שירות (רק אם משתמשים במאגר של כוח עבודה) my-saBYOID_SA_Impersonation_Uriאסימון של Security Token Service שמבוסס על המפרט של החלפת אסימונים urn:ietf:params:oauth:tokentype:id_tokenBYOID_SubjectTokenTypeנקודת הקצה להחלפת אסימונים של Security Token Service https://sts.googleapis.com/v1/tokenBYOID_TokenUri
התקנה והגדרה של מנהל ההתקן של JDBC
כדי להתקין ולהגדיר את מנהל ההתקן של JDBC ל-BigQuery, אתם יכולים להוריד ישירות את קובץ ה-uber-JAR או להשתמש ב-Maven.
הגדרת הורדה ישירה
כדי להגדיר את מנהל ההתקן של JDBC באמצעות הורדה ישירה:
- מורידים את גרסה 1.6.0 של מנהל ההתקן.
- מעתיקים את הקובץ שהורדתם למיקום שצוין בתוכנה.
למידע על שינויים בתכונות ועדכונים בתהליכי עבודה, קראו את יומן השינויים.
הגדרת 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:
מזהים את מחרוזת החיבור של מנהל ההתקן של 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;.... לרשימה המלאה של מאפייני החיבור, ראו מאפייני החיבור.
-
מחברים את אפליקציית 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: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) בהתאמה אישית כדי לשנות את:
|
לא רלוונטי | מחרוזת מופרדת בפסיקים | לא |
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 |
סוג האימות. אחד מהפרטים הבאים:
|
-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:SEVERE2: WARNING3: INFO4: CONFIG5: FINE6: FINER7: FINEST8: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=trueEnableGcpLogExporter=true
הנה דוגמה לכתובת URL של חיבור:
jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=your-project-id;EnableGcpTraceExporter=true;EnableGcpLogExporter=true;
מאפייני החיבור של OpenTelemetry
מאפייני החיבור הבאים נתמכים ב-OpenTelemetry. במאמר מאפייני חיבור תוכלו לקרוא תיאורים מפורטים וערכי ברירת מחדל.
EnableGcpLogExporterEnableGcpTraceExporterGcpTelemetryCredentialsGcpTelemetryProjectIdUseGlobalOpenTelemetry
שיקולים חשובים
כשפורסים את השילוב של 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 :
- מפעילים את ממשקי ה-API:
- מפעילים את Cloud Trace API (
cloudtrace.googleapis.com). - מפעילים את Cloud Logging API (
logging.googleapis.com).
- מפעילים את Cloud Trace API (
- הקצאת תפקידי IAM:
- לייצוא של נתוני מעקב: מקצים לחשבון המשתמש או לחשבון השירות את התפקיד "סוכן Trace" (
roles/cloudtrace.agent). - לייצוא יומנים: מקצים לחשבון המשתמש או לחשבון השירות את התפקיד "כתיבה ביומנים" (
roles/logging.logWriter).
- לייצוא של נתוני מעקב: מקצים לחשבון המשתמש או לחשבון השירות את התפקיד "סוכן Trace" (
תמחור וחיוב
כשמשתמשים בטלמטריה ללא הגדרה 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.
המאמרים הבאים
- במאגר הקוד הפתוח ב-GitHub תוכלו למצוא הוראות נוספות להגדרה, מדריכים למאפייני כתובת ה-URL של החיבור, דוגמאות קוד והוראות ליצירת גרסה מקומית:
- מידע נוסף על מנהל ההתקן של ODBC ל-BigQuery
- כלים נוספים למפתחים ב-BigQuery