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

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

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

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

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

הוספת תוויות למערכי נתונים

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

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

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

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

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

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

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

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

הוספת תווית למערך נתונים

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

המסוף

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

2. בקטע Labels שבדף הפרטים של מערך הנתונים, לוחצים על  Edit.

   

3. בתיבת הדו-שיח Edit labels:

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

SQL

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

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

   כניסה ל-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

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

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

המשך

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של 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 ל-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 (roles/bigquery.dataEditor) ב-IAM. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

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

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

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

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

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

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

המסוף

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

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

   

3. בקטע Labels לוחצים על  Edit.

   

4. בתיבת הדו-שיח Edit labels:

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

SQL

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

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

   כניסה ל-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 ומציינים מפתח ייחודי לכל תווית. לדוגמה, כדי להוסיף את התווית 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.update מחליפה את כל המשאב של מערך הנתונים, ולכן צריך להשתמש בשיטה tables.patch.

המשך

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של 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 ל-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 של כלי שורת הפקודה של BigQuery. הכלי bq תומך בהוספת תוויות רק למשימות של שאילתות.

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

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

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

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

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

התפקיד המוגדר מראש הזה כולל את ההרשאה 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 תוכלו לקרוא מידע נוסף.

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

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

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

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

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

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

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

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

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

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

המסוף

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

   כניסה ל-BigQuery

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

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

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

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

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

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

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

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

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

SQL

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

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

   כניסה ל-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. אם בחרתם בקבוצת נתונים, דף הפרטים של קבוצת הנתונים ייפתח באופן אוטומטי. בטבלאות ובתצוגות, לוחצים על Details כדי לפתוח את דף הפרטים.

   

3. בקטע Labels שבדף הפרטים, לוחצים על  Edit.

   

4. בתיבת הדו-שיח Edit labels:

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

SQL

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

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

   כניסה ל-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 כדי לשנות גם תצוגות וגם טבלאות. בנוסף, מכיוון שה-method‏ tables.update מחליפה את כל המשאב של מערך הנתונים, צריך להשתמש ב-method‏ tables.patch במקום זאת.

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

• איך מציגים תוויות במשאבים של BigQuery
• איך מזהים ומנתחים שאילתות שנוצרו על ידי נציגים באמצעות תוויות
• איך מעדכנים תוויות במשאבים של BigQuery
• איך מסננים משאבים באמצעות תוויות
• איך מוחקים תוויות ממשאבים ב-BigQuery
• איך משתמשים בתוויות?