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

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

מנהל ההתקן של ODBC ל-BigQuery זמין במסגרת רישיון Apache 2.0.

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

  1. חשוב לוודא שאתם מכירים את מנהלי ההתקנים ומנהלי ההתקנים של ODBC.

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

    מערכת הפעלה ארכיטקטורות נתמכות גרסת מינימום ותלות
    Windows ‫32 ביט (x86), ‏ 64 ביט (x64) גרסה: Windows 10, ‏ Windows Server 2016 או גרסה מתקדמת יותר

    תלות: Microsoft Visual C++ Redistributable ל-Visual Studio 2019 או 2022
    macOS ‫64 ביט (x86_64), ‏ ARM64 (Apple Silicon) גרסה: macOS 12 (Monterey) ואילך

    תלות: מנהל מנהלי התקנים של ODBC (לדוגמה, unixODBC). חשוב להוסיף את ספריית ההתקנה אל DYLD_LIBRARY_PATH.
    Linux ‫64 ביט (x86_64) גרסה: כל הפצה עם glibc 2.27 ואילך (לדוגמה, Ubuntu 20.04 LTS ואילך, Debian 11 ואילך)

    תלות: מנהל מנהלי התקנים של ODBC (לדוגמה, unixODBC). חשוב להוסיף את ספריית ההתקנה אל LD_LIBRARY_PATH.

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

    שיטת אימות פרטי אימות דוגמה מאפיין של חיבור (להגדרה בהמשך)
    חשבון שירות רגיל מפתח של חשבון שירות (אובייקט JSON) my-sa-key KeyFilePath
    איחוד שירותי אימות הזהות של עומסי העבודה או איחוד שירותי אימות הזהות של כוח העבודה מאפיין הקהל של קובץ ההגדרה של החשבון החיצוני //iam.googleapis.com/locations/global/... BYOID_AudienceUrl
    אחזור טוקנים וקובץ מידע על הסביבה {"file":"/path/to/file"} BYOID_CredentialSource
    פרויקט של משתמש (רק למאגר כוח עבודה) my_project BYOID_PoolUserProject
    סוג אסימון STS id_token BYOID_SubjectTokenType
    נקודת הקצה של החלפת הטוקן של STS https://sts.googleapis.com/v1/token BYOID_TokenUrl
    Application Default Credentials ללא לא רלוונטי לא רלוונטי

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

אפשר להתקין ולהגדיר את מנהל ההתקן של ODBC ל-BigQuery באמצעות מערכת הפעלה של Windows או מערכת הפעלה אחרת.

Windows

  1. מתקינים את מנהל ההתקן שמתאים לארכיטקטורה של האפליקציה:

  2. כדי ליצור שם של מקור נתונים (DSN):

    1. בתפריט Start (התחלה) ב-Windows, עוברים אל ODBC Data Sources (מקורות נתונים של ODBC) ובוחרים את הגרסה עם אותה רמת סיביות כמו באפליקציית הלקוח.
    2. בדף ODBC Data Source Administrator (הכלי לניהול מקורות נתונים של ODBC), לוחצים על הכרטיסייה Drivers (מנהלי התקנים).
    3. ברשימת מנהלי ההתקנים של ODBC, מאתרים את ODBC Driver for BigQuery.
    4. בוחרים בכרטיסייה System DSN כדי ליצור DSN לכל המשתמשים, או בכרטיסייה User DSN כדי ליצור DSN למשתמש הנוכחי. בדרך כלל מומלץ להשתמש ב-DSN של המערכת כי חלק מהאפליקציות טוענות נתונים באמצעות חשבונות משתמש שונים, ויכול להיות שהן לא יזהו DSN אחרים של משתמשים.
    5. לוחצים על הוספה.
    6. בתיבת הדו-שיח יצירת מקור נתונים חדש, בוחרים באפשרות ODBC Driver for BigQuery (מנהל התקן ODBC ל-BigQuery) ולוחצים על סיום. תיבת הדו-שיח ODBC Driver for BigQuery DSN Setup תיפתח.
    7. בשדה שם מקור הנתונים, מזינים שם ל-DSN.
    8. מוסיפים מאפייני קישור. רשימה מלאה של המאפיינים מופיעה במאמר בנושא מאפייני חיבור.

מערכות הפעלה שאינן Windows

  1. מתקינים את מנהל ההתקן שמתאים למערכת ההפעלה:

  2. מחלצים את התוכן של קובץ ה-ZIP או ה-TAR שהורד.

  3. מעבירים את התוכן של קובץ ה-ZIP או ה-TAR לספרייה שבה רוצים להתקין את המחבר. נתיב האובייקט המשותף של מנהל התקן ODBC ל-BigQuery הוא INSTALL_DIR/lib/libgoogle_cloud_odbc_bq_driver.so, כאשר INSTALL_DIR הוא ספריית ההתקנה.

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

    בדוגמה הבאה מתעדכנים קובצי .ini במערכת Linux:

    unzip linux_odbc-driver.VERSION.zip -d linux_odbc-driver.VERSION/
cd ./linux_odbc-driver.VERSION
export INSTALL_DIR=$(pwd)
export ODBCINI=$INSTALL_DIR/odbc.ini
export ODBCINSTINI=$INSTALL_DIR/odbcinst.ini
export GOOGLEBIGQUERYODBCINI=$INSTALL_DIR/googlebigqueryodbc.ini

    מחליפים את VERSION בגרסת הדרייבר.

יצירת חיבור

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

מחרוזת החיבור היא בפורמט הבא:

Driver=ODBC Driver for BigQuery;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

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

  • ‫PROJECT_ID: מזהה הפרויקט ב-BigQuery.
  • ‫AUTH_TYPE: מספר שמציין את סוג האימות שבו השתמשתם. בוחרים אחת מהאפשרויות הבאות:
    • ‫0: לאימות של חשבונות שירות
    • ‫3: לאימות של Application Default Credential
    • ‫4: לאימות באמצעות איחוד שירותי אימות הזהות של עומסי עבודה או איחוד שירותי אימות הזהות של כוח עבודה
  • ‫AUTH_PROPS: פרטי האימות שרשמתם כשביצעתם אימות ב-BigQuery, שמופיעים בפורמט property_1=value_1; property_2=value_2;... – לדוגמה, KeyFilePath=my-sa-key, אם ביצעתם אימות באמצעות חשבון שירות.
  • ‫OTHER_PROPS (אופציונלי): מאפייני חיבור נוספים למנהל התקן ODBC, שמופיעים בפורמט property_1=value_1; property_2=value_2;.... רשימה מלאה של מאפייני החיבור זמינה במאמר מאפייני חיבור.

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

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

נכס חיבור תיאור ערך ברירת המחדל סוג הנתונים חובה
AdditionalProjects פרויקטים שלנהג יש גישה אליהם לשאילתות ולפעולות מטא-נתונים, בנוסף לפרויקט הראשי שמוגדר על ידי המאפיין ProjectId. לא רלוונטי מחרוזת מופרדת בפסיקים לא
AllowHtapiForLargeResults הגדרה שקובעת אם לדרייבר יש אפשרות להשתמש ב-BigQuery Storage Read API. 0 בוליאני לא
AllowLargeResults קובע אם הדרייבר מעבד תוצאות של שאילתות שגדולות מ-128MB כשהמאפיין QueryDialect מוגדר ל-BIG_QUERY. אם המאפיין QueryDialect מוגדר לערך SQL, מנהל ההתקן תמיד מעבד תוצאות גדולות של שאילתות. 0 בוליאני לא
BYOID_AudienceUrl מכיל את שם המשאב של מאגר הזהויות של עומסי העבודה או של מאגר כוח העבודה, ואת מזהה הספק במאגר הזה. לא רלוונטי String רק כשOAuthMechanism=4
BYOID_CredentialSource מגדירה את המידע הנדרש לאחזור האסימון עצמו, וגם מידע על הסביבה. לא רלוונטי String רק כשOAuthMechanism=4
BYOID_PoolUserProject מגדירים את הפרויקט אם מדובר במאגר כוח עבודה ולא במאגר זהויות של עומסי עבודה. לא רלוונטי String רק כשמשתמשים ב-OAuthMechanism=4 ובמאגר כוח עבודה
BYOID_SubjectTokenType הפונקציה מגדירה את סוג הטוקן של STS על סמך המפרט של המרת טוקן OAuth2.0. הערכים הצפויים כוללים:
  • 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
 לא רלוונטי String רק כשOAuthMechanism=4
BYOID_TokenUrl מגדיר את נקודת הקצה של החלפת הטוקן של STS. https://sts.googleapis.com/v1/token String לא
DefaultDataset משמש כמערך נתונים ייעודי בפרויקט, שהדרייבר מפנה אליו באופן אוטומטי כשמריצים שאילתות בלי לציין במפורש מערך נתונים. לא רלוונטי String לא
FilterTablesOnDefaultDataset קובעת את היקף המטא-נתונים שמוחזרים על ידי שיטות של מטא-נתונים של טבלה או עמודה. אם הערך הוא false, לא מתבצע סינון. כדי להפעיל את הסינון, צריך להגדיר גם את הנכס DefaultDataset. FALSE בוליאני לא
EnableSession קובע אם חיבור מתחיל סשן. כשהאפשרות הזו מופעלת, השאילתה הראשונה שמופעלת על ידי החיבור הספציפי הזה מתחילה סשן, והדרייבר מעביר את מזהה הסשן לכל השאילתות הבאות. 0 בוליאני לא
JobCreationMode מאפשרת להפעיל את נתיב השאילתה עם זמן האחזור הנמוך. בוחרים אחת מהאפשרויות הבאות:
  • ‫1: מנהל ההתקן יוצר משימות לכל שאילתה (JOB_CREATION_REQUIRED)
  • ‫2: מנהל ההתקן מריץ שאילתות ללא משימות (JOB_CREATION_OPTIONAL)
 2 מספר שלם לא
KeyFilePath הנתיב למפתח של חשבון השירות כשמשתמשים באימות של חשבון שירות. לא רלוונטי String רק כשOAuthMechanism=0
KMSKeyName מציינים את השם של מפתח ה-KMS שבו רוצים להשתמש להצפנה ולפענוח של נתונים. לא רלוונטי String לא
LargeResultsDataSetId מציין את מערך הנתונים של היעד לאחסון תוצאות גדולות של שאילתות. לא רלוונטי String לא
LargeResultsDatasetExpirationTime מציין את משך החיים של כל הטבלאות במערך הנתונים של התוצאות הגדולות, באלפיות השנייה. 3600000 ארוכה לא
Location מציין את המיקום שבו מנהל ההתקן יוצר מערכי נתונים או שולח אליהם שאילתות. לא רלוונטי String לא
LogLevel מגביל את רמת הפירוט של הנתונים שהנהג רושם במהלך האינטראקציות. בוחרים אחת מהאפשרויות הבאות:
  • 0: OFF
  • 1: ‏ERROR
  • 2: ‏WARNING
  • 3: INFO
 0 מספר שלם לא
LogPath מציינת את הספרייה שבה מנהל ההתקן כותב קובצי יומן. לא רלוונטי String לא
LogFileCount מציינת את המספר המקסימלי של קובצי יומן שיישארו. 0 מספר שלם לא
LogFileSize מציינת את הגודל המקסימלי של כל קובץ יומן בבייטים. 0 ארוכה לא
MaxResults מציין את מספר התוצאות בכל דף בתוצאה של BigQuery API. 10000 ארוכה לא
MaxThreads ההגדרה הזו מגדירה את המספר המקסימלי של שרשורים שהמחבר יכול להשתמש בהם לעיבוד בו-זמני במאגר שרשורים. כדי להגדיר את המאפיין הזה כהגדרה כללית של מחבר למחברים שאינם של Windows, צריך לציין אותו בקובץ googlebigqueryodbc.ini. 8 מספר שלם לא
OAuthMechanism סוג האימות. בוחרים אחת מהאפשרויות הבאות:
  • ‫0: אימות של חשבון שירות
  • ‫3: אימות Application Default Credential
  • ‫4: אימות באמצעות איחוד שירותי אימות הזהות של עומסי עבודה או איחוד שירותי אימות הזהויות של כוח העבודה
 לא רלוונטי מספר שלם כן
ProjectId מזהה הפרויקט שמוגדר כברירת מחדל לדרייבר. הדרייבר משתמש בפרויקט הזה כדי להריץ שאילתות, והחיוב על השימוש במשאבים מתבצע דרך הפרויקט. לא רלוונטי String כן
ProxyHost שם המארח או כתובת ה-IP של שרת Proxy. לא רלוונטי String לא
ProxyPort מספר היציאה שבה שרת ה-proxy מאזין. לא רלוונטי String לא
ProxyPwd הסיסמה לאימות כשמתחברים דרך שרת proxy. לא רלוונטי String לא
ProxyUid שם המשתמש לאימות כשמתחברים דרך שרת proxy. לא רלוונטי String לא
PrivateServiceConnectUris נקודות קצה (endpoints) מותאמות אישית שיחליפו את נקודות הקצה שמוגדרות כברירת מחדל. דוגמאות:
  • BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/
  • READ_API=bigquerystorage.us-east4.rep.googleapis.com
  • OAUTH2=oauth2.us-east4.rep.googleapis.com
 לא רלוונטי מחרוזת מופרדת בפסיקים לא
QueryDialect מציין באיזה ניב של שאילתה להשתמש. משתמשים ב-SQL ל-GoogleSQL (מומלץ מאוד) וב-BIG_QUERY ל-SQL מדור קודם. SQL String לא
QueryProperties הגדרת מאפיינים שיכולים לשנות את התנהגות השאילתה. לא רלוונטי ‫Map<String, String> לא
UniverseDomain מציינים את דומיין היקום של הארגון. googleapis.com String לא
UseQueryCache הפעלת התכונה של שמירת שאילתות במטמון ב-BigQuery. true בוליאני לא

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

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

סוג GoogleSQL סוג SQL של ODBC
INT64SQL_BIGINT
BOOLSQL_BIT
DATESQL_TYPE_DATE
FLOAT64SQL_DOUBLE
TIMESQL_TYPE_TIME
TIMESTAMPSQL_TYPE_TIMESTAMP
DATETIMESQL_TYPE_TIMESTAMP
BYTESSQL_VARBINARY
STRINGSQL_VARCHAR
ARRAYSQL_VARCHAR
STRUCTSQL_VARCHAR
INTERVALSQL_VARCHAR
JSONSQL_VARCHAR
GEOGRAPHYSQL_VARCHAR
RANGESQL_VARCHAR
NUMERICSQL_NUMERIC
BIGNUMERICSQL_NUMERIC

דוגמאות

בדוגמאות הבאות מוסבר איך להשתמש בשאילתות עם פרמטרים ובסקריפטים עם כמה הצהרות באמצעות מנהל התקן ODBC.

שאילתות שמכילות פרמטרים

// 1. Prepare statement
std::string insert_stmt = "INSERT INTO MyTable VALUES (?, ?, ?)";
status = SQLPrepare(hstmt, (SQLCHAR*)insert_stmt.c_str(), SQL_NTS);

// 2. Bind parameters
std::string str_val = "example_string";
long long int_val = 12345;
double float_val = 1.2345;

// Bind string field
status = SQLBindParameter(
    hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0,
    (SQLPOINTER)str_val.c_str(), str_val.size(), NULL);

// Bind integer field
status = SQLBindParameter(
    hstmt, 2, SQL_PARAM_INPUT, SQL_C_UBIGINT, SQL_BIGINT, 0, 0,
    &int_val, 0, NULL);

// Bind float field
status = SQLBindParameter(
    hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DOUBLE, 0, 0,
    &float_val, 0, NULL);

// 3. Execute statement
status = SQLExecute(hstmt);

סקריפטים עם כמה הצהרות

// 1. Prepare and execute the multi-statement script
std::string query =
    "CREATE OR REPLACE TABLE MyTable (StringField STRING, IntegerField INTEGER); "
    "INSERT INTO MyTable VALUES ('example', 123); "
    "SELECT * FROM MyTable;";

status = SQLExecDirect(hstmt, (SQLCHAR*)query.c_str(), SQL_NTS);

// 2. Process results for each statement using SQLMoreResults
do {
    SQLSMALLINT num_cols;
    status = SQLNumResultCols(hstmt, &num_cols);

    if (num_cols > 0) {
        // This is a result-returning statement (e.g., SELECT)
        while (SQLFetch(hstmt) == SQL_SUCCESS) {
            // Process rows...
        }
    } else {
        // This is a non-result statement (e.g., CREATE, INSERT)
        SQLLEN row_count;
        SQLRowCount(hstmt, &row_count);
        // Process affected rows...
    }
} while (SQLMoreResults(hstmt) == SQL_SUCCESS);

תמחור

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

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