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

כדי להריץ משימת BigQuery באופן פרוגרמטי באמצעות ה-API בארכיטקטורת REST או ספריות לקוח:

1. מבצעים קריאה ל-method‏ jobs.insert.
2. מבקשים את משאב העבודה באופן תקופתי ובודקים את מאפיין הסטטוס כדי לדעת מתי העבודה הושלמה.
3. בודקים אם העבודה הסתיימה בהצלחה.

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

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

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

3. אחרי שקוראים לשיטה 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 של כלי שורת הפקודה bq. כלי bq תומך בהוספת תוויות רק למשימות של שאילתות.

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

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

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

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

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

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