הרצת משימות באופן פרוגרמטי

באמצעות BigQuery API בארכיטקטורת REST וספריות הלקוח, אתם יכולים ליצור ולנהל משימות אסינכרוניות כדי להפוך פעולות טעינה, שאילתות, חילוץ והעתקה לאוטומטיות מהאפליקציות שלכם. אחרי שמתחילים משימה באמצעות קריאה ל-method‏ jobs.insert, אפשר לדגום את מאפיין הסטטוס של משאב המשימה כדי לעקוב אחרי השלמת הביצוע ולוודא שהפעולה הצליחה.

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

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

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

כדי להריץ משימה ב-BigQuery, צריך את הרשאת ה-IAM‏ bigquery.jobs.create.

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

• roles/bigquery.user
• roles/bigquery.jobUser
• roles/bigquery.admin

בנוסף, כשאתם יוצרים משימה, אתם מקבלים באופן אוטומטי את ההרשאות הבאות לאותה משימה:

• bigquery.jobs.get
• bigquery.jobs.update

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

משימות פעילות

כדי להריץ משימה באופן פרוגרמטי:

1. מפעילים את המשימה באמצעות קריאה ל-method‏ jobs.insert. כשמפעילים את השיטה jobs.insert, צריך לכלול ייצוג של משאב המשימה.

2. בקטע configuration של משאב המשימה, מוסיפים מאפיין צאצא שמציין את סוג המשימה – load,‏ query,‏ extract או copy.

3. אחרי שקוראים ל-method‏ jobs.insert, בודקים את סטטוס המשימה באמצעות קריאה ל-jobs.get עם מזהה המשימה והמיקום, ובודקים את הערך של status.state כדי לדעת מה סטטוס המשימה. כשהערך של status.state הוא DONE, המשימה הפסיקה לפעול. עם זאת, סטטוס DONE לא אומר שהמשימה הסתיימה בהצלחה, אלא רק שהיא כבר לא פועלת.

   הערה: יש כמה פונקציות wrapper שמנהלות בשבילכם את הבקשות לסטטוס המשימה. לדוגמה, הפעלת jobs.query יוצרת משימה ודוגמת מדי פעם את הסטטוס של DONE למשך פרק זמן מסוים.

4. בודקים שהמשימה בוצעה בהצלחה. אם למשימה יש מאפיין errorResult, המשימה נכשלה. המאפיין status.errorResult מכיל מידע שמתאר מה השתבש במשימה שנכשלה. אם status.errorResult לא מופיע, המשימה הסתיימה בהצלחה, למרות שיכול להיות שהיו כמה שגיאות לא קריטיות, כמו בעיות בייבוא של כמה שורות במשימת טעינה. שגיאות לא קריטיות מוחזרות ברשימה status.errors של המשימה.

הפעלת משימות באמצעות ספריות לקוח

כדי ליצור ולהריץ משימה באמצעות ספריות הלקוח של Cloud ל-BigQuery:

C#

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

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

using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;

public class BigQueryCreateJob
{
    public BigQueryJob CreateJob(string projectId = "your-project-id")
    {
        string query = @"
            SELECT country_name from `bigquery-public-data.utility_us.country_code_iso";

        // Initialize client that will be used to send requests.
        BigQueryClient client = BigQueryClient.Create(projectId);

        QueryOptions queryOptions = new QueryOptions
        {
            JobLocation = "us",
            JobIdPrefix = "code_sample_",
            Labels = new Dictionary<string, string>
            {
                ["example-label"] = "example-value"
            },
            MaximumBytesBilled = 1000000
        };

        BigQueryJob queryJob = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: queryOptions);

        Console.WriteLine($"Started job: {queryJob.Reference.JobId}");
        return queryJob;
    }
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של 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.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.common.collect.ImmutableMap;
import java.util.UUID;

// Sample to create a job
public class CreateJob {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String query = "SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`";
    createJob(query);
  }

  public static void createJob(String query) {
    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();

      // Specify a job configuration to set optional job resource properties.
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              .setLabels(ImmutableMap.of("example-label", "example-value"))
              .build();

      // The location and job name are optional,
      // if both are not specified then client will auto-create.
      String jobName = "jobId_" + UUID.randomUUID().toString();
      JobId jobId = JobId.newBuilder().setLocation("us").setJob(jobName).build();

      // Create a job with job ID
      bigquery.create(JobInfo.of(jobId, queryConfig));

      // Get a job that was just created
      Job job = bigquery.getJob(jobId);
      if (job.getJobId().getJob().equals(jobId.getJob())) {
        System.out.print("Job created successfully." + job.getJobId().getJob());
      } else {
        System.out.print("Job was not created");
      }
    } catch (BigQueryException e) {
      System.out.print("Job was not created. \n" + e.toString());
    }
  }
}

Python

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

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

from google.cloud import bigquery

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

query_job = client.query(
    "SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`",
    # Explicitly force job execution to be routed to a specific processing
    # location.
    location="US",
    # Specify a job configuration to set optional job resource properties.
    job_config=bigquery.QueryJobConfig(
        labels={"example-label": "example-value"}, maximum_bytes_billed=1000000
    ),
    # The client libraries automatically generate a job ID. Override the
    # generated ID with either the job_id_prefix or job_id parameters.
    job_id_prefix="code_sample_",
)  # Make an API request.

print("Started job: {}".format(query_job.job_id))

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

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

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

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

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

איך מוסיפים תוויות למשימות?

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

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