הוספת תוויות למשאבים

בדף הזה מוסבר איך להוסיף תוויות למשאבי BigQuery.

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

מקצים תפקידים של ניהול זהויות והרשאות גישה (IAM) שמעניקים למשתמשים את ההרשאות הדרושות לביצוע כל משימה שמופיעה במאמר הזה. כל ההרשאות שנדרשות לביצוע משימה מפורטות בקטע 'תפקידי IAM נדרשים' של המשימה.

הוספת תוויות לקבוצות נתונים

אפשר להוסיף תווית למערך נתונים ב-BigQuery כשיוצרים אותו באמצעות הפקודה bq mk בכלי שורת הפקודה bq, או באמצעות קריאה לשיטה datasets.insert ב-API. אי אפשר להוסיף תווית למערך נתונים כשיוצרים אותו באמצעות מסוף Google Cloud .

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

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

לפרטים נוספים על הפורמט של תוויות, אפשר לעיין במאמר בנושא דרישות לתוויות.

התפקידים שצריך ב-IAM

כדי לקבל את ההרשאה שנדרשת להוספת תווית למערך נתונים קיים, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ BigQuery Data Owner ‏ (roles/bigquery.dataOwner). להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקיד שמוגדר מראש מכיל את ההרשאה bigquery.datasets.update, שנדרשת כדי להוסיף תווית למערך נתונים קיים.

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

במאמר תפקידים והרשאות מוגדרים מראש יש מידע נוסף על תפקידים והרשאות ב-IAM ב-BigQuery.

הוספת תווית לקבוצת נתונים

כדי להוסיף תווית למערך נתונים אחרי שהוא נוצר:

המסוף

  1. במסוף Google Cloud , בוחרים את מערך הנתונים.

  2. בדף הפרטים של מערך הנתונים, לוחצים על סמל העיפרון משמאל לתוויות.

    עיפרון לסימון.

  3. בתיבת הדו-שיח עריכת תוויות:

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

SQL

משתמשים בהצהרת DDL‏ ALTER SCHEMA SET OPTIONS כדי להגדיר את התוויות במערך נתונים קיים. הגדרת תוויות מחליפה את כל התוויות הקיימות במערך הנתונים. בדוגמה הבאה מוגדרת תווית למערך הנתונים mydataset:

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

    כניסה ל-BigQuery

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

    ALTER SCHEMA mydataset
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

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

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

BQ

כדי להוסיף תווית למערך נתונים קיים, מריצים את הפקודה bq update עם הדגל set_label. חוזרים על הפעולה כדי להוסיף כמה תוויות.

אם מערך הנתונים נמצא בפרויקט שאינו פרויקט ברירת המחדל, מוסיפים את מזהה הפרויקט למערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

bq update --set_label KEY:VALUE PROJECT_ID:DATASET

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

  • ‫KEY:VALUE: צמד מפתח/ערך של תווית שרוצים להוסיף. המפתח חייב להיות ייחודי. המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ומותרים תווים בינלאומיים.
  • PROJECT_ID: מזהה הפרויקט.
  • ‫DATASET: מערך הנתונים שאתם מתייגים.

דוגמאות:

כדי להוסיף תווית למעקב אחרי מחלקות, מזינים את הפקודה bq update ומציינים את department כמפתח התווית. לדוגמה, כדי להוסיף את התווית department:shipping ל-mydataset בפרויקט ברירת המחדל, מזינים:

    bq update --set_label department:shipping mydataset

כדי להוסיף כמה תוויות למערך נתונים, חוזרים על האפשרות set_label ומציינים מפתח ייחודי לכל תווית. לדוגמה, כדי להוסיף את התווית department:shipping ואת התווית cost_center:logistics ל-mydataset בפרויקט ברירת המחדל, מזינים:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset

API

כדי להוסיף תווית למערך נתונים קיים, קוראים לשיטה datasets.patch ומאכלסים את המאפיין labels עבור משאב מערך הנתונים.

השיטה המועדפת היא datasets.patch, כי השיטה datasets.update מחליפה את כל משאב מערך הנתונים.

Go

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Goהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Go API.

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

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

בדוגמה הזו נעשה שימוש ב-Google HTTP Client Library for Java כדי לשלוח בקשה ל-BigQuery API.

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Javaהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Java API.

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Node.jsהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Node.js API.

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Python API.

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


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

הוספת תוויות לטבלאות ולתצוגות

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

מכיוון שהתצוגות נחשבות למשאבי טבלה, משתמשים בשיטה tables.patch כדי לשנות גם תצוגות וגם טבלאות.

התפקידים שצריך ב-IAM

כדי לקבל את ההרשאות שנדרשות להוספת תווית לטבלה או לתצוגה קיימות, צריך לבקש מהאדמין לתת לכם את תפקיד BigQuery Data Editor ‏ (roles/bigquery.dataEditor) ב-IAM. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

ההרשאות הנדרשות

כדי להוסיף תווית לטבלה או לתצוגה קיימות, נדרשות ההרשאות הבאות:

  • bigquery.tables.update
  • bigquery.tables.get

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

במאמר תפקידים והרשאות מוגדרים מראש יש מידע נוסף על תפקידים והרשאות ב-IAM ב-BigQuery.

הוספת תווית לטבלה או לתצוגה

כדי להוסיף תווית לטבלה או לתצוגה קיימות:

המסוף

  1. במסוף Google Cloud , בוחרים את הטבלה או התצוגה.

  2. לוחצים על הכרטיסייה פרטים.

    פרטי הטבלה.

  3. לוחצים על סמל העיפרון משמאל לתוויות.

    עיפרון לסימון.

  4. בתיבת הדו-שיח עריכת תוויות:

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

SQL

משתמשים בהצהרת DDL‏ ALTER TABLE SET OPTIONS כדי להגדיר את התוויות בטבלה קיימת, או בהצהרת DDL‏ ALTER VIEW SET OPTIONS כדי להגדיר את התוויות בתצוגה קיימת. הגדרת תוויות מחליפה את כל התוויות הקיימות בטבלה או בתצוגה. בדוגמה הבאה מוגדרות שתי תוויות בטבלה mytable:

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

    כניסה ל-BigQuery

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

    ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels = [('department', 'shipping'), ('cost_center', 'logistics')]);

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

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

BQ

כדי להוסיף תווית לטבלה או לתצוגה קיימות, מריצים את הפקודה bq update עם הדגל set_label. כדי להוסיף כמה תוויות, חוזרים על התג.

אם הטבלה או התצוגה נמצאות בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט למערך הנתונים בפורמט הבא: project_id:dataset.

bq update \
--set_label KEY:VALUE \
PROJECT_ID:DATASET.TABLE_OR_VIEW

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

  • ‫KEY:VALUE: צמד מפתח/ערך של תווית שרוצים להוסיף. המפתח חייב להיות ייחודי. המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ומותרים תווים בינלאומיים.
  • PROJECT_ID: מזהה הפרויקט.
  • ‫DATASET: מערך הנתונים שמכיל את הטבלה או התצוגה שאתם מתייגים.
  • ‫TABLE_OR_VIEW: השם של הטבלה או התצוגה שאתם מוסיפים להם תווית.

דוגמאות:

כדי להוסיף תווית לטבלה למעקב אחרי מחלקות, מזינים את הפקודה bq update ומציינים את department כמפתח התווית. לדוגמה, כדי להוסיף את התווית department:shipping ל-mytable בפרויקט ברירת המחדל, מזינים:

    bq update --set_label department:shipping mydataset.mytable

כדי להוסיף תווית לתצוגה מפורטת למעקב אחרי מחלקות, מזינים את הפקודה bq update ומציינים את department כמפתח התווית. לדוגמה, כדי להוסיף את התווית department:shipping ל-myview בפרויקט ברירת המחדל, מזינים:

    bq update --set_label department:shipping mydataset.myview

כדי להוסיף כמה תוויות לטבלה או לתצוגה, חוזרים על set_label flag ומציינים מפתח ייחודי לכל תווית. לדוגמה, כדי להוסיף את התווית department:shipping ואת התווית cost_center:logistics ל-mytable בפרויקט ברירת המחדל, מזינים:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset.mytable

API

כדי להוסיף תווית לטבלה או לתצוגה קיימות, קוראים ל-method‏ tables.patch ומאכלסים את המאפיין labels של משאב הטבלה.

מכיוון שהתצוגות נחשבות למשאבי טבלה, משתמשים בשיטה tables.patch כדי לשנות גם תצוגות וגם טבלאות.

השיטה המועדפת היא tables.patch, כי השיטה tables.update מחליפה את כל משאב מערך הנתונים.

Go

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Goהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Go API.

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

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

בדוגמה הזו נעשה שימוש ב-Google HTTP Client Library for Java כדי לשלוח בקשה ל-BigQuery API.

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Javaהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Java API.

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Node.jsהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Node.js API.

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Python API.

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

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # API request

labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

print(f"Added {table.labels} to {table_id}.")

הוספת תוויות למשרות

אפשר להוסיף תוויות לעבודות של שאילתות דרך שורת הפקודה באמצעות הדגל --label של כלי שורת הפקודה bq. הכלי bq תומך בהוספת תוויות רק לעבודות של שאילתות.

אפשר גם להוסיף תווית לעבודה כששולחים אותה דרך ה-API. לשם כך, צריך לציין את המאפיין labels בהגדרת העבודה כשמפעילים את השיטה jobs.insert. אפשר להשתמש ב-API כדי להוסיף תוויות לכל סוג עבודה.

אי אפשר להוסיף תוויות למשימות בהמתנה, למשימות שפועלות או למשימות שהושלמו, ואי אפשר לעדכן את התוויות שלהן.

כשמוסיפים תווית לעבודה, התווית נכללת בנתוני החיוב.

התפקידים שצריך ב-IAM

כדי לקבל את ההרשאה שדרושה להוספת תווית לעבודה, צריך לבקש מהאדמין לתת לכם את תפקיד ה-IAM‏ BigQuery User ‏ (roles/bigquery.user). להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקיד המוגדר מראש הזה כולל את ההרשאה bigquery.jobs.create, שנדרשת כדי להוסיף תווית לעבודה.

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

במאמר תפקידים והרשאות מוגדרים מראש יש מידע נוסף על תפקידים והרשאות ב-IAM ב-BigQuery.

הוספת תווית למשרה

כדי להוסיף תווית למשרה:

BQ

כדי להוסיף תווית לעבודת שאילתה, מריצים את הפקודה bq query עם הדגל --label. כדי להוסיף כמה תוויות, חוזרים על התג. הדגל מציין שהשאילתה שלכם היא בתחביר GoogleSQL.

bq query --label KEY:VALUE  'QUERY'

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

  • ‫KEY:VALUE: צמד מפתח/ערך של תווית שרוצים להוסיף למשימת השאילתה. המפתח חייב להיות ייחודי. המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ואפשר להשתמש בתווים בינלאומיים. כדי להוסיף כמה תוויות למשימת שאילתה, חוזרים על האפשרות --label ומציינים מפתח ייחודי לכל תווית.
  • ‫QUERY: שאילתת GoogleSQL תקינה.

דוגמאות:

כדי להוסיף תווית לעבודת שאילתה, מזינים:

    bq query \
    --label department:shipping \
     \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

כדי להוסיף כמה תוויות לעבודת שאילתה, חוזרים על האפשרות --label ומציינים מפתח ייחודי לכל תווית. לדוגמה, כדי להוסיף את התווית department:shipping ואת התווית cost_center:logistics לעבודת שאילתה, מזינים:

    bq query \
    --label department:shipping \
    --label cost_center:logistics \
     \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

API

כדי להוסיף תווית למשימה, קוראים ל-method‏ jobs.insert ומאכלסים את המאפיין labels של הגדרת המשימה. אפשר להשתמש ב-API כדי להוסיף תוויות לכל סוג העבודה.

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Python API.

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

from google.cloud import bigquery

client = bigquery.Client()

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""
labels = {"color": "green"}

config = bigquery.QueryJobConfig()
config.labels = labels
location = "us"
job = client.query(sql, location=location, job_config=config)
job_id = job.job_id

print(f"Added {job.labels} to {job_id}.")

שיוך משרות בהפעלה לתווית

אם אתם מריצים שאילתות בסשן, אתם יכולים להקצות תווית לכל עבודות השאילתות העתידיות בסשן באמצעות שאילתות מרובות הצהרות ב-BigQuery.

SQL

מגדירים את משתנה המערכת @@query_label בסשן על ידי הפעלת השאילתה הבאה:

  SET @@query_label = "KEY:VALUE";

  • ‫KEY:VALUE: צמד מפתח/ערך של התווית שיוקצה לכל השאילתות העתידיות בסשן. אפשר גם להוסיף כמה צמדים של מפתח/ערך, מופרדים בפסיק (לדוגמה, SET @@query_label = "key1:value1,key2:value2"). המפתח חייב להיות ייחודי. המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ומותר להשתמש בתווים בינלאומיים.

דוגמה:

  SET @@query_label = "cost_center:logistics";

API

כדי להוסיף תווית לעבודת שאילתה בסשן כשמריצים שאילתה באמצעות קריאה ל-API, צריך להפעיל את method‏ jobs.insert ולאכלס את המאפיין query_label של connectionProperties הגדרות העבודה.

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

הוספת תווית להזמנה

כשמוסיפים תווית להזמנה, התווית נכללת בנתוני החיוב. אתם יכולים להשתמש בתוויות כדי לסנן את המק"ט של משבצות הניתוח בשיוך בנתוני החיוב ב-Cloud.

במק"ט Analysis Slots Attribution מתועד רק השימוש במשבצות. הוא לא מתעד עלויות של מק"טים של BigQuery Reservation API. אי אפשר להשתמש בתוויות של מקומות שמורים כמסננים למק"טים של BigQuery Reservation API.

מידע נוסף על שימוש בתוויות בנתוני החיוב זמין במאמר שימוש במסננים כדי לצמצם את הנתונים.

התפקידים שצריך ב-IAM

כדי לקבל את ההרשאה שנדרשת להוספת תווית להזמנה, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ BigQuery Resource Editor (roles/bigquery.resourceEditor) בפרויקט הניהול. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקיד שמוגדר מראש מכיל את ההרשאה bigquery.reservations.update, שנדרשת כדי להוסיף תווית להזמנה.

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

הוספת תווית להזמנה

כדי להוסיף תווית להזמנה:

המסוף

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. בתפריט הניווט, לוחצים על ניהול קיבולת.

  3. לוחצים על הכרטיסייה Slot reservations.

  4. מאתרים את ההזמנה שרוצים לעדכן.

  5. מרחיבים את האפשרות Actions (פעולות).

  6. לוחצים על Edit.

  7. כדי להרחיב את הקטע הגדרות מתקדמות, לוחצים על החץ להרחבה .

  8. לוחצים על הוספת תווית.

  9. מזינים את צמד המפתח/ערך. כדי להחיל תוויות נוספות, לוחצים על הוספת תווית.

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

SQL

כדי להוסיף תווית להזמנה, משתמשים בהצהרת ALTER RESERVATION SET OPTIONS DDL. הגדרת תוויות מחליפה את כל התוויות הקיימות בהזמנה. בדוגמה הבאה מוגדרת תווית להזמנה myreservation:

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

    כניסה ל-BigQuery

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

    ALTER RESERVATION myreservation
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

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

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

BQ

כדי להוסיף תווית להזמנה, מריצים את הפקודה bq update עם הדגל set_label והדגל --reservation. כדי להוסיף כמה תוויות, חוזרים על השימוש בדגל set_label.

bq update --set_label KEY:VALUE --location LOCATION --reservation RESERVATION_NAME

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

  • ‫KEY:VALUE: זוג של מפתח וערך של תווית שרוצים להוסיף להזמנה. המפתח חייב להיות ייחודי. המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ואפשר להשתמש בתווים בינלאומיים. כדי להוסיף כמה תוויות להזמנה, חוזרים על הדגל --set_label ומציינים מפתח ייחודי לכל תווית.
  • ‫LOCATION: המיקום של ההזמנה. הדגל location לא יכול להיות האחרון בפקודה, אחרת השגיאה FATAL Flags positioning מוחזרת.
  • ‫RESERVATION_NAME: השם של ההזמנה.

הוספת תווית ללא ערך

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

תוויות ללא ערכים יכולות להיות שימושיות במצבים שבהם אתם מתייגים משאב, אבל לא צריך את הפורמט של צמד מפתח/ערך. לדוגמה, אם טבלה מכילה נתוני בדיקה שמשמשים כמה קבוצות, כמו תמיכה או פיתוח, אפשר להוסיף לטבלה את התווית test_data כדי לזהות אותה.

כדי להוסיף תווית בלי ערך:

המסוף

  1. במסוף Google Cloud , בוחרים את המשאב המתאים (מערך נתונים, טבלה או תצוגה).

  2. לגבי מערכי נתונים, דף הפרטים של מערך הנתונים נפתח באופן אוטומטי. כדי לפתוח את דף הפרטים של טבלאות ותצוגות, לוחצים על פרטים.

    פרטי הטבלה.

  3. בדף הפרטים, לוחצים על סמל העיפרון משמאל לתוויות.

    עיפרון לסימון.

  4. בתיבת הדו-שיח עריכת תוויות:

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

SQL

כדי להוסיף תווית ללא ערך, משתמשים בהצהרת DDL‏ ALTER TABLE SET OPTIONS:

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

    כניסה ל-BigQuery

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

    ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels=[("key1", ""), ("key2", "")]);

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

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

BQ

כדי להוסיף תווית ללא ערך למשאב קיים, משתמשים בפקודה bq update עם הדגל set_label. מציינים את המפתח, ואחריו נקודתיים, אבל לא מציינים את הערך.

bq update --set_label KEY: RESOURCE_ID

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

  • ‫KEY:: מפתח התווית שרוצים להשתמש בו.
  • ‫RESOURCE_ID: שם חוקי של מערך נתונים, טבלה או תצוגה. אם המשאב נמצא בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט בפורמט הבא: PROJECT_ID:DATASET.

דוגמאות:

מזינים את הפקודה הבאה כדי ליצור תווית test_data עבור mydataset.mytable. ‫mydataset נמצא בפרויקט ברירת המחדל שלכם.

bq update --set_label test_data: mydataset

API

קוראים למתודה datasets.patch או למתודה tables.patch ומוסיפים תוויות עם הערך שמוגדר למחרוזת ריקה ("") במקור הנתונים או בטבלת המקור. כדי להסיר ערכים מתוויות קיימות, מחליפים את הערכים שלהן במחרוזת ריקה.

מכיוון שהתצוגות נחשבות למשאבי טבלה, משתמשים בשיטה tables.patch כדי לשנות גם תצוגות וגם טבלאות. בנוסף, מכיוון שהשיטה tables.update מחליפה את כל משאב מערך הנתונים, עדיף להשתמש בשיטה tables.patch.

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