סינון משאבים באמצעות תוויות

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

• משתמשים בסרגל החיפוש במסוף Google Cloud .
• יוצרים מפרט מסנן לשימוש ב-API, בכלי שורת הפקודה של BigQuery או בספריות הלקוח.

מגבלות

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

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

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

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

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

• ‫bigquery.datasets.get (מאפשר סינון של מערכי נתונים)
• bigquery.tables.get (מאפשר לסנן טבלאות ותצוגות)

כל אחד מתפקידי ה-IAM הבאים שמוגדרים מראש כולל את ההרשאות שנדרשות לסינון מערכי נתונים:

• roles/bigquery.user
• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

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

• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

בנוסף, אם יש לכם את ההרשאה bigquery.datasets.create, אתם יכולים לסנן את המשאבים שאתם יוצרים.

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

סינון משאבים במסוף Google Cloud

כדי ליצור רשימה מסוננת של משאבים, משתמשים במסוף Google Cloud :

1. במסוף Google Cloud , עוברים לחלונית Explorer.

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

   לדוגמה, כדי להציג רק קבוצות נתונים עם התווית department:shipping, אפשר להזין department או department:shipping.

סינון של מערכי נתונים ב-API או בכלי שורת הפקודה של BigQuery

ממשק ה-API, כלי שורת הפקודה של BigQuery וספריות הלקוח תומכים בסינון רק של מערכי נתונים.

כדי לסנן מערכי נתונים באמצעות ה-API, הכלי bq או ספריות לקוח, צריך ליצור מפרט מסנן ולהשתמש בו:

• כפרמטר של הדגל --filter בכלי bq
• כערך של המאפיין filter בשיטה datasets.list של ה-API

המגבלות על הגדרות מסננים

המגבלות הבאות חלות על מפרטי מסננים:

• יש תמיכה רק באופרטור הלוגי AND. השוואות שמופרדות ברווחים נחשבות כהשוואות עם אופרטורים מרומזים של AND.
• השדה היחיד שאפשר לסנן הוא labels.key, כאשר key הוא שם התווית.
• כל key בביטוי סינון חייב להיות ייחודי.
• המסנן יכול לכלול עד עשרה ביטויים.
• הסינון תלוי אותיות רישיות (case-sensitive).
• ממשק ה-API, כלי שורת הפקודה של BigQuery וספריות הלקוח תומכים בסינון רק של מערכי נתונים.

דוגמאות למפרטי מסננים

התחביר של הגדרת מסנן הוא:

"field[:value][ field[:value]]..."

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

• ‫field מבוטא כ-labels.key, כאשר key הוא מפתח התווית.
• ‫value הוא ערך אופציונלי של תווית.

בדוגמאות הבאות מוסבר איך ליצור ביטויי סינון.

כדי להציג רשימה של משאבים עם התווית department:shipping, משתמשים במפרט המסנן הבא:

labels.department:shipping

כדי להציג רשימה של משאבים באמצעות כמה תוויות, מפרידים בין זוגות התוויות key:value באמצעות רווח. הרווח נחשב לאופרטור לוגי AND. לדוגמה, כדי להציג רשימה של מערכי נתונים עם התווית department:shipping והתווית location:usa, משתמשים במפרט המסנן הבא:

labels.department:shipping labels.location:usa

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

labels.department

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

labels.department:*

אפשר גם להשתמש בתגים במפרט של מסנן. לדוגמה, כדי להציג רשימה של משאבים עם התווית department:shipping והתג test_data, משתמשים במפרט המסנן הבא:

labels.department:shipping labels.test_data

סינון של מערכי נתונים בכלי שורת הפקודה של BigQuery וב-API

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

BQ

מריצים את הפקודה bq ls עם הדגל --filter. אם אתם מציגים רשימה של מערכי נתונים בפרויקט שאינו פרויקט ברירת המחדל, צריך לציין את הדגל --project_id.

bq ls \
--filter "filter_specification" \
--project_id project_id

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

• ‫filter_specification היא הגדרת מסנן תקינה.
• ‫project_id הוא מזהה הפרויקט.

דוגמאות:

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

bq ls --filter "labels.department:shipping"

מריצים את הפקודה הבאה כדי להציג רשימה של מערכי נתונים בפרויקט ברירת המחדל שיש להם תווית department:shipping ותג test_data.

bq ls --filter "labels.department:shipping labels.test_data"

מזינים את הפקודה הבאה כדי להציג רשימה של מערכי נתונים ב-myotherproject עם תווית department:shipping:

bq ls --filter "labels.department:shipping" --project_id myotherproject

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

+-----------+
| datasetId |
+-----------+
| mydataset |
| mydataset2|
+-----------+

API

מבצעים קריאה לשיטת ה-API‏ datasets.list ומספקים את מפרט המסנן באמצעות המאפיין filter.

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listDatasetsByLabel demonstrates walking the collection of datasets in a project, and
// filtering that list to a subset that has specific label metadata.
func listDatasetsByLabel(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	it := client.Datasets(ctx)
	it.Filter = "labels.color:green"
	for {
		dataset, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
	}
	return nil
}

Java

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

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

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get list of datasets by label
public class ListDatasetsByLabel {

  public static void runListDatasetsByLabel() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String filter = "MY_LABEL_FILTER";
    listDatasetsByLabel(projectId, filter);
  }

  public static void listDatasetsByLabel(String projectId, String filter) {
    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();

      Page<Dataset> datasets =
          bigquery.listDatasets(
              projectId,
              BigQuery.DatasetListOption.pageSize(100),
              BigQuery.DatasetListOption.labelFilter(filter)); // "labels.color:green"
      if (datasets == null) {
        System.out.println("Dataset does not contain any models");
        return;
      }
      datasets
          .iterateAll()
          .forEach(
              dataset -> System.out.printf("Success! Dataset ID: %s ", dataset.getDatasetId()));
    } catch (BigQueryException e) {
      System.out.println("Project does not contain any datasets \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 listDatasetsByLabel() {
  // Lists all datasets in current GCP project, filtering by label color:green.

  const options = {
    filter: 'labels.color:green',
  };
  // Lists all datasets in the specified project
  const [datasets] = await bigquery.getDatasets(options);

  console.log('Datasets:');
  datasets.forEach(dataset => console.log(dataset.id));
}

Python

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

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

from google.cloud import bigquery

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

label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))  # Make an API request.

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:
        print("\t{}.{}".format(dataset.project, dataset.dataset_id))
else:
    print("No datasets found with this filter.")

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

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