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

כדי להריץ משימת 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.