יצירת טבלאות אובייקטים

המסוף

1. עוברים לדף IAM & Admin.

   כניסה לדף IAM & Admin

2. לוחצים על person_add הוספה.

   תיבת הדו-שיח Add principals נפתחת.

3. בשדה New principals, מזינים את מזהה חשבון השירות שהעתקתם קודם.

4. בשדה Select a role, בוחרים באפשרות Cloud Storage ואז באפשרות Storage Object Viewer.

5. לוחצים על Save.

gcloud

משתמשים בפקודה gcloud projects add-iam-policy-binding.

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

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

• ‫PROJECT_NUMBER: מספר הפרויקט שבו רוצים להעניק את התפקיד.
• ‫MEMBER: מזהה חשבון השירות שהעתקתם קודם.

SQL

משתמשים בהצהרה CREATE EXTERNAL TABLE.

1. במסוף Google Cloud , עוברים לדף BigQuery.

   כניסה ל-BigQuery

2. מזינים את ההצהרה הבאה בעורך השאילתות:

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
   WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');

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

   • PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET_ID: המזהה של מערך הנתונים שאמור להכיל את טבלת האובייקטים.
   • ‫TABLE_NAME: השם של טבלת האובייקטים.
   • ‫REGION: האזור או מספר האזורים שכוללים את החיבור.
   • ‫CONNECTION_ID: המזהה של החיבור למשאב ב-Cloud שבו רוצים להשתמש עם טבלת האובייקטים הזו. החיבור קובע באיזה חשבון שירות המערכת משתמשת כדי לקרוא נתונים מ-Cloud Storage.

     כשמציגים את פרטי החיבור במסוף Google Cloud , מזהה החיבור הוא הערך בקטע האחרון של מזהה החיבור המלא שמוצג במזהה החיבור – לדוגמה, projects/myproject/locations/connection_location/connections/myconnection.

     כדי להשתמש ב חיבור ברירת מחדל, מציינים DEFAULT במקום מחרוזת החיבור שמכילה PROJECT_ID.REGION.CONNECTION_ID.

   • ‫BUCKET_PATH: הנתיב לקטגוריה של Cloud Storage שמכילה את האובייקטים שמיוצגים על ידי טבלת האובייקטים, בפורמט ['gs://bucket_name/[folder_name/]*'].

     אפשר להשתמש בתו כללי לחיפוש (*) בכל נתיב כדי להגביל את האובייקטים שייכללו בטבלת האובייקטים. לדוגמה, אם המאגר מכיל כמה סוגים של נתונים לא מובְנים, אפשר ליצור את טבלת האובייקטים רק על אובייקטים מסוג PDF על ידי ציון ['gs://bucket_name/*.pdf']. מידע נוסף זמין במאמר תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

     אפשר לציין כמה דליים לאפשרות uris על ידי ציון כמה נתיבים, לדוגמה ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

     מידע נוסף על שימוש בכתובות URI של Cloud Storage ב-BigQuery זמין במאמר בנושא נתיב משאב של Cloud Storage.

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

     כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

     כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מרווח זמן בין 30 דקות ל-7 ימים. לדוגמה, כדי להגדיר את מרווח הזמן של הנתונים הלא עדכניים ל-4 שעות, מציינים INTERVAL 4 HOUR. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים ששמורים במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

   • ‫CACHE_MODE: מציין אם המטמון של המטא-נתונים מתרענן באופן אוטומטי או ידני. מידע נוסף על שיקולים בנוגע לשמירה במטמון של מטא-נתונים זמין במאמר שמירה במטמון של מטא-נתונים לשיפור הביצועים.

     אם מגדירים את הערך AUTOMATIC, מטמון המטא-נתונים מתעדכן במרווח זמן שמוגדר על ידי המערכת, בדרך כלל בין 30 ל-60 דקות.

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

     אם הערך של STALENESS_INTERVAL גדול מ-0, צריך להגדיר את CACHE_MODE.

3. לוחצים על play_circle הפעלה.

מידע נוסף על הרצת שאילתות זמין במאמר הרצת שאילתה אינטראקטיבית.

דוגמאות

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

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

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

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

בדוגמה הבאה נוצרת טבלת אובייקטים רק על אובייקטים מסוג PDF בקטגוריה של Cloud Storage:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

BQ

משתמשים בפקודה bq mk.

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

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

• PROJECT_ID: מזהה הפרויקט.
• ‫DATASET_ID: המזהה של מערך הנתונים שאמור להכיל את טבלת האובייקטים.
• ‫TABLE_NAME: השם של טבלת האובייקטים.
• ‫REGION: האזור או מספר האזורים שכוללים את החיבור.
• ‫CONNECTION_ID: המזהה של החיבור למשאב ב-Cloud שבו רוצים להשתמש עם הטבלה החיצונית הזו. החיבור קובע באיזה חשבון שירות משתמשים כדי לקרוא נתונים מ-Cloud Storage.

  כשמציגים את פרטי החיבור במסוף Google Cloud , מזהה החיבור הוא הערך בקטע האחרון של מזהה החיבור המלא שמוצג במזהה החיבור – לדוגמה, projects/myproject/locations/connection_location/connections/myconnection.

• ‫BUCKET_PATH: הנתיב לקטגוריה של Cloud Storage שמכילה את האובייקטים שמיוצגים על ידי טבלת האובייקטים, בפורמט gs://bucket_name/[folder_name/]*.

  אפשר להשתמש בתו כללי לחיפוש (*) בכל נתיב כדי להגביל את האובייקטים שייכללו בטבלת האובייקטים. לדוגמה, אם המאגר מכיל כמה סוגים של נתונים לא מובְנים, אפשר ליצור את טבלת האובייקטים רק על אובייקטים מסוג PDF על ידי ציון gs://bucket_name/*.pdf. מידע נוסף זמין במאמר תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

  אפשר לציין כמה דליים לאפשרות uris על ידי ציון כמה נתיבים, לדוגמה gs://mybucket1/*,gs://mybucket2/folder5/*.

  מידע נוסף על שימוש בכתובות URI של Cloud Storage ב-BigQuery זמין במאמר בנושא נתיב משאב של Cloud Storage.

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

  כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

  כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מרווח זמן בין 30 דקות ל-7 ימים, באמצעות הפורמט Y-M D H:M:S שמתואר במסמכי התיעוד של סוג הנתונים INTERVAL. לדוגמה, מציינים 0-0 0 4:0:0 למרווח זמן של 4 שעות. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים ששמורים במטמון, אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

• ‫CACHE_MODE: מציין אם המטמון של המטא-נתונים מתרענן באופן אוטומטי או ידני. מידע נוסף על שיקולים בנוגע לשמירה במטמון של מטא-נתונים זמין במאמר שמירה במטמון של מטא-נתונים לשיפור הביצועים.

  אם מגדירים את הערך AUTOMATIC, מטמון המטא-נתונים מתעדכן במרווח זמן שמוגדר על ידי המערכת, בדרך כלל בין 30 ל-60 דקות.

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

  אם הערך של STALENESS_INTERVAL גדול מ-0, צריך להגדיר את CACHE_MODE.

דוגמאות

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

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

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

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

בדוגמה הבאה נוצרת טבלת אובייקטים רק על אובייקטים מסוג PDF בקטגוריה של Cloud Storage:

bq mk --table \
--external_table_definition=gs://bucket1/*.pdf@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

מבצעים קריאה ל-tables.insert. כוללים אובייקט ExternalDataConfiguration עם השדה objectMetadata שמוגדר לערך SIMPLE במשאב Table שמעבירים.

בדוגמה הבאה מוצג איך להפעיל את המתודה הזו באמצעות curl:

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

שדות המפתח שצריך לציין עבור טבלת אובייקטים הם google_bigquery_table.external_data_configuration.object_metadata,‏ google_bigquery_table.external_data_configuration.metadata_cache_mode ו-google_bigquery_table.max_staleness. מידע נוסף על כל משאב זמין במאמרי העזרה של Terraform BigQuery.

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  table_id   = "my-table-id"
  dataset_id = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.default
  ]
}

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

הכנת Cloud Shell

1. מפעילים את Cloud Shell.

2. מגדירים את פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform. Google Cloud

   תצטרכו להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ותוכלו לעשות זאת בכל ספרייה.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

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

   מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

   לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
4. שומרים את השינויים.
5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.

   terraform init

   אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:

   terraform init -upgrade

החלה של השינויים

1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:

   terraform apply

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

3. פותחים את Google Cloud הפרויקט כדי לראות את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.