תזמון שאילתות

שאילתות מתוזמנות ב-BigQuery מאפשרות להפוך עומסי עבודה חוזרים של GoogleSQL לאוטומטיים, כולל הצהרות של שפת הגדרת נתונים (DDL) ושל שפת טיפול בנתונים (DML). כדי לארגן את התוצאות לפי תאריך ושעה, אפשר להגדיר פרמטרים גם למחרוזת השאילתה וגם לטבלת היעד. כשיוצרים או מעדכנים לוח זמנים, BigQuery ממיר את הזמן המתוזמן מהשעון המקומי ל-UTC, שלא מושפע משעון קיץ.

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

• שאילתות מתוזמנות משתמשות בתכונות של שירות העברת הנתונים ל-BigQuery. מוודאים שביצעתם את כל הפעולות שנדרשות כדי להפעיל את שירות העברת הנתונים ל-BigQuery.
• להקצות תפקידים של ניהול זהויות והרשאות גישה (IAM) שנותנים למשתמשים את ההרשאות שנדרשות כדי לבצע כל משימה שמופיעה במסמך הזה.
• אם אתם מתכננים לציין מפתח הצפנה בניהול הלקוח (CMEK), ודאו שלחשבון השירות יש הרשאות להצפנה ולפענוח, ושיש לכם את מזהה המשאב של מפתח Cloud KMS שנדרש כדי להשתמש ב-CMEK. במאמר ציון מפתח הצפנה בשאילתות מתוזמנות מוסבר איך CMEK פועל עם שירות העברת הנתונים ל-BigQuery.

מגבלות

• שאילתות מתוזמנות שפועלות בדיוק בשעה עגולה (לדוגמה, 09:00) עשויות לפעול כמה פעמים, מה שעלול לגרום לתוצאות לא מכוונות כמו שכפול נתונים מפעולות INSERT. כדי למנוע תוצאות לא מכוונות כאלה, כדאי להשתמש בלוח זמנים שלא מתחיל בשעה עגולה (לדוגמה, 08:58 או 09:03).

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

כדי לתזמן שאילתה, אתם צריכים את הרשאות ה-IAM הבאות:

• כדי ליצור את ההעברה, צריכות להיות לכם ההרשאות bigquery.transfers.update ו-bigquery.datasets.get, או ההרשאות bigquery.jobs.create,‏ bigquery.transfers.get ו-bigquery.datasets.get.

  הערה: אם אתם משתמשים במסוף Google Cloud או בכלי שורת הפקודה של BigQuery כדי לתזמן שאילתה, אתם צריכים את ההרשאה bigquery.transfers.get.

• כדי להריץ שאילתה מתוזמנת, אתם צריכים:

  • ההרשאה bigquery.datasets.get במערך הנתונים המיועד.
  • ההרשאה bigquery.jobs.create בפרויקט.

כדי לשנות או למחוק שאילתה מתוזמנת, צריך אחד מהתפקידים הבאים:

• ההרשאות bigquery.transfers.update ו-bigquery.transfers.get בפרויקט.
• אם אתם מריצים שאילתה מתוזמנת באמצעות פרטי כניסה של משתמש, המשתמש צריך להיות הבעלים של השאילתה המתוזמנת, ואתם צריכים את ההרשאה bigquery.jobs.create בפרויקט.
• אם אתם מריצים שאילתה מתוזמנת כחשבון שירות, למשתמש ששולח קריאה לשאילתה המתוזמנת צריכות להיות ההרשאות bigquery.transfers.update ו-bigquery.transfers.get בפרויקט. הקצאת התפקיד משתמש בחשבון שירות של IAM (iam.serviceAccountUser) מאפשרת למשתמש להריץ משימות בתור חשבון השירות, אבל לא מקנה הרשאות ניהול של הגדרת השאילתה המתוזמנת.

תפקיד ה-IAM המוגדר מראש אדמין ב-BigQuery‏ (roles/bigquery.admin) כולל את ההרשאות שנדרשות כדי לתזמן או לשנות שאילתה.

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

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

• ‫iam.serviceAccounts.list כדי להציג את רשימת חשבונות השירות.
• iam.serviceAccountUser כדי להקצות חשבון שירות לשאילתה מתוזמנת.

הערה: אם אתם משתמשים בכלי שורת הפקודה של BigQuery, השתמשו בדגל --service_account_name במקום לבצע אימות כחשבון שירות.

אפשרויות להגדרות אישיות

בקטעים הבאים מתוארות אפשרויות ההגדרה.

מחרוזת השאילתה

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

כדי לבדוק באופן ידני מחרוזת שאילתה עם הפרמטרים @run_time ו-@run_date לפני שמתזמנים שאילתה, משתמשים בכלי שורת הפקודה של BigQuery.

הפרמטרים הזמינים

פרמטר	סוג GoogleSQL	ערך
@run_time	TIMESTAMP	התאריך מוצג לפי שעון UTC. בשאילתות שנקבעו באופן קבוע, run_time מייצג את זמן ההפעלה המיועד. לדוגמה, אם השאילתה המתוזמנת מוגדרת ל "כל 24 שעות", ההפרש של run_time בין שתי שאילתות עוקבות הוא בדיוק 24 שעות, למרות שזמן הביצוע בפועל עשוי להשתנות מעט.
@run_date	DATE	מייצג תאריך לוגי ביומן.

דוגמה

הפרמטר @run_time הוא חלק ממחרוזת השאילתה בדוגמה הזו, ששולחת שאילתה למערך נתונים ציבורי בשם hacker_news.stories.

SELECT @run_time AS time,
  title,
  author,
  text
FROM `bigquery-public-data.hacker_news.stories`
LIMIT
  1000

טבלת היעד

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

אם אתם משתמשים בשאילתת DDL או DML, בחרו את Processing location או את האזור במסוף Google Cloud . צריך לציין מיקום עיבוד לשאילתות DDL או DML שיוצרות את טבלת היעד.

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

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

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

העדפת כתיבה

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

• ‫WRITE_TRUNCATE: אם הטבלה קיימת, BigQuery מחליף את נתוני הטבלה.
• ‫WRITE_APPEND: אם הטבלה קיימת, BigQuery מוסיף את הנתונים לטבלה.

אם אתם משתמשים בשאילתת DDL או DML, אתם לא יכולים להשתמש באפשרות של העדפת כתיבה.

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

סידור באשכולות

שאילתות מתוזמנות יכולות ליצור אשכולות רק בטבלאות חדשות, כשהטבלה נוצרת באמצעות הצהרת DDL‏ CREATE TABLE AS SELECT. אפשר לקרוא מידע נוסף במאמר יצירת טבלה מסודרת באשכולות מתוצאת שאילתה בדף שימוש בהצהרות של שפת הגדרת נתונים (DDL).

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

שאילתות מתוזמנות יכולות ליצור טבלאות יעד מחולקות למחיצות או לא מחולקות למחיצות. אפשר להגדיר חלוקה למחיצות במסוף Google Cloud , בכלי שורת הפקודה של BigQuery וב-API. אם אתם משתמשים בשאילתת DDL או DML עם חלוקה למחיצות, השאירו את השדה Destination table partitioning ריק.

ב-BigQuery אפשר להשתמש בסוגים הבאים של חלוקה למחיצות בטבלאות:

• חלוקה לפי טווח של מספרים שלמים: טבלאות שמחולקות לפי טווחים של ערכים בעמודה ספציפית של INTEGER.
• חלוקה למחיצות לפי עמודת יחידת זמן: טבלאות שמחולקות למחיצות לפי עמודה מסוג TIMESTAMP,‏ DATE או DATETIME.
• חלוקה למחיצות לפי זמן הטמעה: טבלאות שמחולקות למחיצות לפי זמן ההטמעה. ‫BigQuery מקצה שורות למחיצות באופן אוטומטי על סמך הזמן שבו BigQuery מטמיע את הנתונים.

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

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

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

• כדי להשתמש בחלוקה למחיצות לפי זמן הטמעה, משאירים את השדה Destination table partitioning ריק ומציינים את החלוקה למחיצות לפי תאריך בשם של טבלת היעד. לדוגמה, mytable${run_date}. מידע נוסף זמין במאמר תחביר של תבניות פרמטרים.

הפרמטרים הזמינים

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

פרמטר	סוג התבנית	ערך
run_time	חותמת זמן בפורמט	לפי שעון UTC, בהתאם ללוח הזמנים. בשאילתות שנקבעו באופן קבוע, run_time מייצג את זמן ההפעלה המיועד. לדוגמה, אם השאילתה המתוזמנת מוגדרת ל "כל 24 שעות", ההפרש של run_time בין שתי שאילתות עוקבות הוא בדיוק 24 שעות, למרות שזמן הביצוע בפועל עשוי להשתנות מעט. אפשר לעיין בקטע TransferRun.runTime.
run_date	מחרוזת תאריך	התאריך של הפרמטר run_time בפורמט הבא: %Y-%m-%d, לדוגמה: 2018-01-01. הפורמט הזה תואם לטבלאות שמחולקות למחיצות (Partitions) לפי זמני הטמעת הנתונים.

מערכת תבניות

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

תחביר של תבניות פרמטרים

תחביר התבניות תומך בתבניות בסיסיות של מחרוזות ובהזמן שחלף. הפרמטרים מופיעים בפורמטים הבאים:

• {run_date}
• {run_time[+\-offset]|"time_format"}

פרמטר	מטרה
run_date	הפרמטר הזה מוחלף בתאריך בפורמט YYYYMMDD.
run_time	הפרמטר הזה תומך במאפיינים הבאים: offset הזמן שחלף מצוין בשעות (h), דקות (m) ושניות (s) בסדר הזה. אין תמיכה בימים (d). אפשר להשתמש במספרים עשרוניים, לדוגמה: 1.5h. time_format מחרוזת עיצוב. הפרמטרים הנפוצים ביותר לעיצוב הם שנים (%Y), חודשים (%m) וימים (%d). בטבלאות מחולקות למחיצות, הסיומת הנדרשת היא YYYYMMDD – זה שווה ערך ל-"%Y%m%d". מידע נוסף על הפורמט של רכיבי תאריך ושעה

הערות לגבי השימוש:

• אסור להוסיף רווחים בין run_time,‏ offset ופורמט הזמן.
• כדי לכלול סוגריים מסולסלים במחרוזת, אפשר להוסיף להם תו בריחה (escape) כמו '\{' and '\}'.
• כדי לכלול מירכאות או קו אנכי ב-time_format, כמו "YYYY|MM|DD", אפשר להוסיף להם תו בריחה במחרוזת הפורמט, למשל: '\"' או '\|'.

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

בדוגמאות האלה אפשר לראות איך מציינים שמות של טבלאות יעד בפורמטים שונים של זמן, ואיך משנים את זמן ההרצה.

run_time (UTC)	פרמטר של תבנית	שם טבלת היעד של הפלט
2018-02-15 00:01:00	mytable	mytable
2018-02-15 00:01:00	mytable_{run_time|"%Y%m%d"}	mytable_20180215
2018-02-15 00:01:00	mytable_{run_time+25h|"%Y%m%d"}	mytable_20180216
2018-02-15 00:01:00	mytable_{run_time-1h|"%Y%m%d"}	mytable_20180214
2018-02-15 00:01:00	mytable_{run_time+1.5h|"%Y%m%d%H"} או mytable_{run_time+90m|"%Y%m%d%H"}	mytable_2018021501
2018-02-15 00:01:00	{run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"}	20180215_mytable_000237

הערה: כשמשתמשים בפרמטרים של תאריך או שעה כדי ליצור טבלאות עם שמות שמסתיימים בפורמט תאריך כמו YYYYMMDD, מערכת BigQuery מקבלת את הטבלאות האלה יחד. במסוף Google Cloud , יכול להיות שהטבלאות המקובצות האלה יוצגו עם שם כמו mytable_(1), שמייצג את אוסף הטבלאות המפוצלות.

שימוש בחשבון שירות

אתם יכולים להגדיר שאילתה מתוזמנת לאימות כחשבון שירות. חשבון שירות הוא חשבון מיוחד שמשויך לפרויקט ב- Google Cloud . חשבון השירות יכול להריץ משימות, כמו שאילתות מתוזמנות או צינורות עיבוד נתונים ברצף (batch processing), באמצעות פרטי הכניסה של השירות עצמו במקום פרטי הכניסה של משתמש קצה.

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

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

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

ציון מפתח הצפנה עם שאילתות מתוזמנות

אתם יכולים לציין מפתחות הצפנה בניהול הלקוח (CMEK) כדי להצפין נתונים להרצת העברה. אתם יכולים להשתמש ב-CMEK כדי לתמוך בהעברות משאילתות מתוזמנות.

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

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

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

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

הגדרת שאילתות מתוזמנות באמצעות חשבון שירות

Java

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

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create a scheduled query with service account
public class CreateScheduledQueryWithServiceAccount {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String serviceAccount = "MY_SERVICE_ACCOUNT";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createScheduledQueryWithServiceAccount(projectId, transferConfig, serviceAccount);
  }

  public static void createScheduledQueryWithServiceAccount(
      String projectId, TransferConfig transferConfig, String serviceAccount) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .setServiceAccountName(serviceAccount)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println(
          "\nScheduled query with service account created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query with service account was not created." + ex.toString());
    }
  }
}

Python

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

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

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

# The project where the query job runs is the same as the project
# containing the destination dataset.
project_id = "your-project-id"
dataset_id = "your_dataset_id"

# This service account will be used to execute the scheduled queries. Omit
# this request parameter to run the query as the user with the credentials
# associated with this client.
service_account_name = "[e-mail]"

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = transfer_client.common_project_path(project_id)

transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=dataset_id,
    display_name="Your Scheduled Query Name",
    data_source_id="scheduled_query",
    params={
        "query": query_string,
        "destination_table_name_template": "your_table_{run_date}",
        "write_disposition": "WRITE_TRUNCATE",
        "partitioning_field": "",
    },
    schedule="every 24 hours",
)

transfer_config = transfer_client.create_transfer_config(
    bigquery_datatransfer.CreateTransferConfigRequest(
        parent=parent,
        transfer_config=transfer_config,
        service_account_name=service_account_name,
    )
)

print("Created scheduled query '{}'".format(transfer_config.name))

הצגת הסטטוס של שאילתה מתוזמנת

המסוף

כדי לראות את הסטטוס של השאילתות המתוזמנות, בתפריט הניווט לוחצים על Scheduling ומסננים לפי Scheduled Query. לוחצים על שאילתה מתוזמנת כדי לקבל פרטים נוספים עליה.

BQ

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

מזינים את הפקודה bq ls ומציינים את דגל ההעברה --transfer_config. צריך גם את הדגלים הבאים:

• --transfer_location

לדוגמה:

bq ls \
--transfer_config \
--transfer_location=us

כדי להציג את הפרטים של שאילתה מתוזמנת אחת, מזינים את הפקודה bq show ומציינים את הערך של transfer_path של השאילתה המתוזמנת או של הגדרת ההעברה.

לדוגמה:

bq show \
--transfer_config \
projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38

API

משתמשים ב-method‏ projects.locations.transferConfigs.list ומספקים מופע של המשאב TransferConfig.

Java

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

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ListTransferConfigsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import java.io.IOException;

// Sample to get list of transfer config
public class ListTransferConfigs {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    listTransferConfigs(projectId);
  }

  public static void listTransferConfigs(String projectId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      ListTransferConfigsRequest request =
          ListTransferConfigsRequest.newBuilder().setParent(parent.toString()).build();
      dataTransferServiceClient
          .listTransferConfigs(request)
          .iterateAll()
          .forEach(config -> System.out.print("Success! Config ID :" + config.getName() + "\n"));
    } catch (ApiException ex) {
      System.out.println("Config list not found due to error." + ex.toString());
    }
  }
}

Python

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

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

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer_v1

client = bigquery_datatransfer_v1.DataTransferServiceClient()


def list_transfer_configs(project_id: str, location: str) -> None:
    """Lists transfer configurations in a given project.

    This sample demonstrates how to list all transfer configurations in a project.

    Args:
        project_id: The Google Cloud project ID.
        location: The geographic location of the transfer config, for example "us-central1"
    """

    parent = client.common_location_path(project_id, location)

    try:
        for config in client.list_transfer_configs(parent=parent):
            print(f"Name: {config.name}")
            print(f"Display Name: {config.display_name}")
            print(f"Data source: {config.data_source_id}")
            print(f"Destination dataset: {config.destination_dataset_id}")
            if "time_based_schedule" in config.schedule_options_v2:
                print(
                    f"Schedule: {config.schedule_options_v2.time_based_schedule.schedule}"
                )
            else:
                print("Schedule: None")
            print("---")
    except google.api_core.exceptions.NotFound:
        print(
            f"Error: Project '{project_id}' not found or contains no transfer configs."
        )
    except google.api_core.exceptions.PermissionDenied:
        print(
            f"Error: Permission denied for project '{project_id}'. Please ensure you have the correct permissions."
        )

עדכון שאילתות מתוזמנות

המסוף

כדי לעדכן שאילתה מתוזמנת:

1. בתפריט הניווט, לוחצים על Scheduled queries או על Scheduling.
2. ברשימת השאילתות המתוזמנות, לוחצים על שם השאילתה שרוצים לשנות.
3. בדף Scheduled query details שנפתח, לוחצים על Edit.
4. אופציונלי: משנים את הטקסט של השאילתה בחלונית העריכה של השאילתה.
5. לוחצים על Schedule query ובוחרים באפשרות Update scheduled query.
6. אופציונלי: משנים את אפשרויות התזמון האחרות של השאילתה.
7. לוחצים על עדכון.

BQ

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

מזינים את הפקודה bq update עם הדגל הנדרש --transfer_config.

דגלים אופציונליים:

• ‫--project_id הוא מזהה הפרויקט. אם לא מציינים את --project_id, המערכת משתמשת בפרויקט שמוגדר כברירת מחדל.

• ‫--schedule היא התדירות שבה רוצים להריץ את השאילתה. אם לא מציינים את --schedule, ברירת המחדל היא "כל 24 שעות" על סמך זמן היצירה.

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

• ‫--target_dataset (אופציונלי לשאילתות DDL ו-DML) היא דרך חלופית לתת שם למערך הנתונים של היעד לתוצאות השאילתה, כשמשתמשים בשאילתות DDL ו-DML.

• ‫--display_name הוא השם של השאילתה המתוזמנת.

• ‫--params הפרמטרים של הגדרת ההעברה שנוצרה, בפורמט JSON. לדוגמה: ‎--params='{"param":"param_value"}'‎.

• ‫--destination_kms_key מציין את מזהה משאב המפתח של מפתח Cloud KMS, אם משתמשים במפתח הצפנה בניהול הלקוח (CMEK) להעברה הזו. במאמר ציון מפתח הצפנה עם שאילתות מתוזמנות מוסבר איך מפתחות הצפנה בניהול הלקוח (CMEK) פועלים עם שירות העברת הנתונים ל-BigQuery.

bq update \
--target_dataset=dataset \
--display_name=name \
--params='parameters'
--transfer_config \
RESOURCE_NAME

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

• ‫dataset. מערך הנתונים לטירגוט של הגדרות ההעברה. הפרמטר הזה הוא אופציונלי לשאילתות DDL ו-DML. הוא נדרש לכל שאר השאילתות.
• ‫name. השם המוצג של הגדרות ההעברה. השם המוצג יכול להיות כל ערך שתוכלו לזהות מאוחר יותר אם תצטרכו לשנות את השאילתה.
• ‫parameters. מכיל את הפרמטרים של הגדרות ההעברה שנוצרו בפורמט JSON. לדוגמה: --params='{"param":"param_value"}'.
  • בשאילתה מתוזמנת, צריך לספק את הפרמטר query.
  • הפרמטר destination_table_name_template הוא השם של טבלת היעד. הפרמטר הזה הוא אופציונלי לשאילתות DDL ו-DML. הוא נדרש בכל שאר השאילתות.
  • בפרמטר write_disposition, אתם יכולים לבחור באפשרות WRITE_TRUNCATE כדי לחתוך (להחליף) את טבלת היעד, או באפשרות WRITE_APPEND כדי להוסיף את תוצאות השאילתה לטבלת היעד. הפרמטר הזה אופציונלי בשאילתות DDL ו-DML. הוא נדרש בכל שאר השאילתות.
• אופציונלי: --destination_kms_key מציין את מזהה המשאב של המפתח ב-Cloud KMS, לדוגמה projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
• RESOURCE_NAME: שם המשאב של ההעברה (נקרא גם הגדרות ההעברה). אם אתם לא יודעים את שם המשאב של ההעברה, אתם יכולים למצוא אותו באמצעות: bq ls --transfer_config --transfer_location=location.

הערה: כדי לכתוב תוצאות בטבלה שמחולקת למחיצות לפי זמני כתיבת הנתונים, קראו את ההוראות בקטע טבלת היעד. שאילתה מתוזמנת נכשלת אם יוצרים הגדרת העברה שבה הפרמטר destination_table_name_template מוגדר לטבלה מחולקת למחיצות (Partitions) לפי זמני כתיבת הנתונים, וגם מופיעה שגיאה אם הפרמטר partitioning_field מוגדר לטבלה מחולקת למחיצות (Partitions) לפי זמני כתיבת הנתונים.

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

לדוגמה, הפקודה הבאה מעדכנת הגדרת העברה של שאילתה מתוזמנת בשם My Scheduled Query באמצעות השאילתה SELECT 1 from mydataset.test. טבלת היעד mytable נחתכת בכל כתיבה, ומערך הנתונים של היעד הוא mydataset:

bq update \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}'
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

משתמשים ב-method‏ projects.transferConfigs.patch ומציינים את שם המשאב של ההעברה באמצעות הפרמטר transferConfig.name. אם אתם לא יודעים את שם המשאב של ההעברה, אתם יכולים להשתמש בפקודה bq ls --transfer_config --transfer_location=location כדי להציג את כל ההעברות, או להפעיל את ה-method‏ projects.locations.transferConfigs.list ולציין את מזהה הפרויקט באמצעות הפרמטר parent.

Java

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

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update transfer config.
public class UpdateTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setName(configId)
            .setDisplayName("UPDATED_DISPLAY_NAME")
            .build();
    FieldMask updateMask = FieldMaskUtil.fromString("display_name");
    updateTransferConfig(transferConfig, updateMask);
  }

  public static void updateTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config updated successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not updated." + ex.toString());
    }
  }
}

Python

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

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

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer_v1
from google.protobuf import field_mask_pb2


client = bigquery_datatransfer_v1.DataTransferServiceClient()


def update_transfer_config(
    project_id: str,
    location: str,
    transfer_config_id: str,
) -> None:
    """Updates a data transfer configuration.

    This sample shows how to update the display name for a transfer
    configuration.

    Args:
        project_id: The Google Cloud project ID.
        location: The geographic location of the transfer config, for example "us-central1"
        transfer_config_id: The transfer configuration ID
    """
    transfer_config_name = client.transfer_config_path(
        project=f"{project_id}/locations/{location}",
        transfer_config=transfer_config_id,
    )

    transfer_config = bigquery_datatransfer_v1.types.TransferConfig(
        name=transfer_config_name,
        display_name="My New Transfer Config display name",
    )
    update_mask = field_mask_pb2.FieldMask(paths=["display_name"])

    try:
        response = client.update_transfer_config(
            transfer_config=transfer_config,
            update_mask=update_mask,
        )

        print(f"Updated transfer config: {response.name}")
        print(f"New display name: {response.display_name}")
    except google.api_core.exceptions.NotFound:
        print(f"Error: Transfer config '{transfer_config_name}' not found.")

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

עדכון שאילתות מתוזמנות עם הגבלות בעלות

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

Cannot modify restricted parameters without taking ownership of the transfer configuration.

הבעלים של שאילתה מתוזמנת הוא הזהות שפרטי הכניסה שלה משמשים להרצת השאילתה:

• פרטי כניסה של משתמש: אם השאילתה פועלת כמשתמש, המשתמש הזה הוא הבעלים.
• פרטי כניסה לחשבון שירות: אם השאילתה פועלת כחשבון שירות, חשבון השירות הוא הבעלים.

חשוב לדעת: אם השאילתה המתוזמנת מוגדרת לפעול כחשבון שירות, חשבון השירות הוא הבעלים של השאילתה, אבל הוא לא יכול לנהל את ההגדרות של השאילתה המתוזמנת. כדי לנהל או למחוק את השאילתה המתוזמנת, צריך לקבל את ההרשאה bigquery.transfers.update בפרויקט.

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

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

• טקסט השאילתה
• מערך הנתונים של היעד
• תבנית השם של טבלת היעד

עדכון פרטי הכניסה של שאילתה מתוזמנת

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

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

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

• אתם רוצים להריץ שאילתה על נתונים ב-Google Drive בשאילתה מתוזמנת.

• כשמנסים לתזמן את השאילתה, מקבלים את השגיאה INVALID_USER:

  Error code 5 : Authentication failure: User Id not found. Error code: INVALID_USERID

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

  Cannot modify restricted parameters without taking ownership of the transfer configuration.

הערה: אם אתם לא הבעלים של השאילתה המתוזמנת, כדי לעדכן את פרטי הכניסה של השאילתה המתוזמנת, אתם צריכים את ההרשאה bigquery.transfers.update בפרויקט ב- Google Cloud . למידע נוסף, קראו את המאמר ההרשאות הנדרשות.

המסוף

כדי לרענן את פרטי הכניסה הקיימים בשאילתה מתוזמנת:

1. מאתרים את השאילתה המתוזמנת וצופים בסטטוס שלה.

2. לוחצים על הלחצן MORE (עוד) ובוחרים באפשרות Update credentials (עדכון פרטי הכניסה).

   

3. השינוי ייכנס לתוקף תוך 10 עד 20 דקות. יכול להיות שתצטרכו לנקות את המטמון של הדפדפן.

זהירות: אי אפשר להשתמש במסוף Google Cloud כדי לשנות את פרטי הכניסה שמשמשים לשאילתה מתוזמנת לחשבון שירות.

BQ

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

מזינים את הפקודה bq update ומציינים את דגל ההעברה --transfer_config. צריך גם את הדגלים הבאים:

• --update_credentials

דגל אופציונלי:

• ‫--service_account_name משמש לאימות השאילתה המתוזמנת באמצעות חשבון שירות במקום חשבון המשתמש שלכם.

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

bq update \
--update_credentials \
--service_account_name=abcdef-test-sa@abcdef-test. \
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Java

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

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update credentials in transfer config.
public class UpdateCredentials {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    String serviceAccount = "MY_SERVICE_ACCOUNT";
    TransferConfig transferConfig = TransferConfig.newBuilder().setName(configId).build();
    FieldMask updateMask = FieldMaskUtil.fromString("service_account_name");
    updateCredentials(transferConfig, serviceAccount, updateMask);
  }

  public static void updateCredentials(
      TransferConfig transferConfig, String serviceAccount, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .setServiceAccountName(serviceAccount)
              .build();
      dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Credentials updated successfully");
    } catch (ApiException ex) {
      System.out.print("Credentials was not updated." + ex.toString());
    }
  }
}

Python

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

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

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

service_account_name = "[e-mail]"
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["service_account_name"]),
        "service_account_name": service_account_name,
    }
)

print("Updated config: '{}'".format(transfer_config.name))

הגדרה של הפעלה ידנית בתאריכים היסטוריים

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

לדוגמה, בכל יום בשעה 09:00 אתם שולחים שאילתה לטבלת מקור כדי למצוא שורות שתואמות לתאריך הנוכחי. עם זאת, אתם מגלים שבשלושת הימים האחרונים לא נוספו נתונים לטבלת המקור. במצב כזה, אתם יכולים להגדיר שהשאילתה תפעל על נתונים היסטוריים בטווח תאריכים שתציינו. השאילתה פועלת באמצעות שילובים של הפרמטרים run_date ו-run_time, שתואמים לתאריכים שהגדרתם בשאילתה המתוזמנת.

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

המסוף

אחרי שלוחצים על Schedule כדי לשמור את השאילתה המתוזמנת, אפשר ללחוץ על הלחצן Scheduled queries כדי לראות את רשימת השאילתות המתוזמנות. לוחצים על שם תצוגה כלשהו כדי לראות את פרטי התזמון של השאילתה. בפינה השמאלית העליונה של הדף, לוחצים על Schedule backfill כדי לציין טווח תאריכים היסטורי.

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

אזהרה: טווחי התאריכים שאתם מספקים הם ב-UTC, אבל לוח הזמנים של השאילתה מוצג באזור הזמן המקומי שלכם (כדי לעקוף את הבעיה הזו, עיינו בדוגמה 2).

דוגמה 1

השאילתה המתוזמנת מוגדרת לפעול בשעה every day 09:00 לפי שעון החוף המערבי של ארה"ב. חסרים נתונים מ-1 בינואר, מ-2 בינואר ומ-3 בינואר. בוחרים את טווח התאריכים ההיסטורי הבא:

Start Time = 1/1/19
End Time = 1/4/19

השאילתה פועלת באמצעות הפרמטרים run_date ו-run_time, שתואמים לזמנים הבאים:

• ‫1/1/19 09:00 שעון החוף המערבי של ארה"ב
• ‫2.1.19 בשעה 09:00 לפי שעון החוף המערבי של ארה"ב
• ‫3 בינואר 2019, 09:00 שעון החוף המערבי של ארה"ב

דוגמה 2

השאילתה המתוזמנת מוגדרת לפעול בשעה every day 23:00 לפי שעון החוף המערבי של ארה"ב. חסרים נתונים מ-1 בינואר, מ-2 בינואר ומ-3 בינואר. בוחרים את טווחי התאריכים ההיסטוריים הבאים (התאריכים המאוחרים יותר נבחרים כי התאריך ב-UTC שונה בשעה 23:00 לפי שעון החוף המערבי של ארה"ב):

Start Time = 1/2/19
End Time = 1/5/19

השאילתה פועלת באמצעות הפרמטרים run_date ו-run_time, שתואמים לזמנים הבאים:

• ‫2.1.2019 בשעה 06:00 לפי שעון UTC, או 1.1.2019 בשעה 23:00 לפי שעון החוף המערבי
• ‫3 בינואר 2019 בשעה 06:00 לפי שעון UTC, או 2 בינואר 2019 בשעה 23:00 לפי שעון החוף המערבי של ארה"ב
• ‫1/4/19 06:00 UTC, או 1/3/2019 23:00 שעון החוף המערבי

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

BQ

כדי להריץ את השאילתה באופן ידני על טווח תאריכים היסטורי:

מזינים את הפקודה bq mk ומציינים את הדגל של הרצת ההעברה --transfer_run. צריך גם את הדגלים הבאים:

• --start_time
• --end_time

bq mk \
--transfer_run \
--start_time='start_time' \
--end_time='end_time' \
resource_name

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

• ‫start_time וגם end_time. חותמות זמן שמסתיימות ב-Z או מכילות היסט תקין של אזור זמן. דוגמאות:
  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00
• ‫resource_name. שם המשאב של השאילתה המתוזמנת (או של ההעברה). שם המשאב נקרא גם הגדרת ההעברה.

לדוגמה, הפקודה הבאה מתזמנת מילוי חוסרים למשאב של שאילתה מתוזמנת (או הגדרת העברה): projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

  bq mk \
  --transfer_run \
  --start_time 2017-05-25T00:00:00Z \
  --end_time 2017-05-25T00:00:00Z \
  projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

מידע נוסף זמין במאמר bq mk --transfer_run.

API

משתמשים ב-method‏ projects.locations.transferConfigs.scheduleRun ומספקים נתיב למשאב TransferConfig.

Java

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

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsResponse;
import com.google.protobuf.Timestamp;
import java.io.IOException;
import org.threeten.bp.Clock;
import org.threeten.bp.Instant;
import org.threeten.bp.temporal.ChronoUnit;

// Sample to run schedule back fill for transfer config
public class ScheduleBackFill {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    Clock clock = Clock.systemDefaultZone();
    Instant instant = clock.instant();
    Timestamp startTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(5, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(5, ChronoUnit.DAYS).getNano())
            .build();
    Timestamp endTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(2, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(2, ChronoUnit.DAYS).getNano())
            .build();
    scheduleBackFill(configId, startTime, endTime);
  }

  public static void scheduleBackFill(String configId, Timestamp startTime, Timestamp endTime)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ScheduleTransferRunsRequest request =
          ScheduleTransferRunsRequest.newBuilder()
              .setParent(configId)
              .setStartTime(startTime)
              .setEndTime(endTime)
              .build();
      ScheduleTransferRunsResponse response = client.scheduleTransferRuns(request);
      System.out.println("Schedule backfill run successfully :" + response.getRunsCount());
    } catch (ApiException ex) {
      System.out.print("Schedule backfill was not run." + ex.toString());
    }
  }
}

Python

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

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

import datetime

from google.cloud.bigquery_datatransfer_v1 import (
    DataTransferServiceClient,
    StartManualTransferRunsRequest,
)

# Create a client object
client = DataTransferServiceClient()

# Replace with your transfer configuration name
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
now = datetime.datetime.now(datetime.timezone.utc)
start_time = now - datetime.timedelta(days=5)
end_time = now - datetime.timedelta(days=2)

# Some data sources, such as scheduled_query only support daily run.
# Truncate start_time and end_time to midnight time (00:00AM UTC).
start_time = datetime.datetime(
    start_time.year, start_time.month, start_time.day, tzinfo=datetime.timezone.utc
)
end_time = datetime.datetime(
    end_time.year, end_time.month, end_time.day, tzinfo=datetime.timezone.utc
)

requested_time_range = StartManualTransferRunsRequest.TimeRange(
    start_time=start_time,
    end_time=end_time,
)

# Initialize request argument(s)
request = StartManualTransferRunsRequest(
    parent=transfer_config_name,
    requested_time_range=requested_time_range,
)

# Make the request
response = client.start_manual_transfer_runs(request=request)

# Handle the response
print("Started manual transfer runs:")
for run in response.runs:
    print(f"backfill: {run.run_time} run: {run.name}")

הגדרת התראות לגבי שאילתות מתוזמנות

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

מחיקת שאילתות מתוזמנות

המסוף

כדי למחוק שאילתה מתוזמנת בדף Scheduled queries במסוף Google Cloud :

1. בתפריט הניווט, לוחצים על Scheduled queries.
2. ברשימת השאילתות המתוזמנות, לוחצים על השם של השאילתה שרוצים למחוק.

3. בדף Scheduled query details, לוחצים על Delete.

   

אפשר גם למחוק שאילתה מתוזמנת בדף Scheduling במסוף Google Cloud :

1. בתפריט הניווט, לוחצים על תזמון.
2. ברשימת השאילתות המתוזמנות, לוחצים על התפריט Actions של השאילתה המתוזמנת שרוצים למחוק.

3. בוחרים את האפשרות Delete.

   

Java

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

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.DeleteTransferConfigRequest;
import java.io.IOException;

// Sample to delete a transfer config
public class DeleteTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    String configId = "MY_CONFIG_ID";
    deleteTransferConfig(configId);
  }

  public static void deleteTransferConfig(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      DeleteTransferConfigRequest request =
          DeleteTransferConfigRequest.newBuilder().setName(configId).build();
      dataTransferServiceClient.deleteTransferConfig(request);
      System.out.println("Transfer config deleted successfully");
    } catch (ApiException ex) {
      System.out.println("Transfer config was not deleted." + ex.toString());
    }
  }
}

Python

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

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

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer_v1

client = bigquery_datatransfer_v1.DataTransferServiceClient()


def delete_transfer_config(
    project_id: str, location: str, transfer_config_id: str
) -> None:
    """Deletes a data transfer configuration, including any associated transfer runs and logs.

    Args:
        project_id: The Google Cloud project ID.
        location: The geographic location of the transfer configuration, for example, "us-central1".
        transfer_config_id: The transfer configuration ID, for example, "1234a-5678-90b1-2c3d-4e5f67890g12".
    """

    name = client.transfer_config_path(
        project=f"{project_id}/locations/{location}",
        transfer_config=transfer_config_id,
    )
    request = bigquery_datatransfer_v1.DeleteTransferConfigRequest(name=name)

    try:
        client.delete_transfer_config(request=request)
        print(f"Deleted transfer config {name}")
    except google.api_core.exceptions.NotFound:
        print(f"Error: Transfer config '{name}' not found.")

השבתה או הפעלה של שאילתות מתוזמנות

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

כדי להשבית תזמון של שאילתה שנבחרה:

1. בתפריט הניווט של מסוף Google Cloud , לוחצים על Scheduling.
2. ברשימת השאילתות המתוזמנות, לוחצים על התפריט Actions של השאילתה המתוזמנת שרוצים להשבית.

3. לוחצים על השבתה.

   

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

מכסות

שאילתות מתוזמנות תמיד מופעלות כמשימות של שאילתות באצווה, וכפופות לאותן מכסות ומגבלות של BigQuery כמו שאילתות ידניות.

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

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

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

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

תמחור

התמחור של שאילתות מתוזמנות זהה לתמחור של שאילתות ידניות ב-BigQuery.

אזורים נתמכים

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

אפשר להשתמש בשאילתות מתוזמנות במיקומים הבאים.

אזורים

בטבלה הבאה מפורטים האזורים ביבשת אמריקה שבהם BigQuery זמין.

תיאור האזור	שם האזור	פרטים
קולומבוס, אוהיו	us-east5
דאלאס	us-south1	‫ רמה נמוכה של CO2‎
אייווה	us-central1	‫ רמה נמוכה של CO2‎
לוס אנג'לס	us-west2
לאס וגאס	us-west4
מקסיקו	northamerica-south1
מונטריאול	northamerica-northeast1	‫ רמה נמוכה של CO2‎
צפון וירג'יניה	us-east4
אוקלהומה	us-central2	‫ רמה נמוכה של CO2‎
אורגון	us-west1	‫ רמה נמוכה של CO2‎
סולט לייק סיטי	us-west3
סאו פאולו	southamerica-east1	‫ רמה נמוכה של CO2‎
סנטיאגו	southamerica-west1	‫ רמה נמוכה של CO2‎
דרום קרוליינה	us-east1
טורונטו	northamerica-northeast2	‫ רמה נמוכה של CO2‎

בטבלה הבאה מפורטים האזורים באסיה והאוקיינוס השקט שבהם BigQuery זמין.

תיאור האזור	שם האזור	פרטים
בנגקוק	asia-southeast3
דלהי	asia-south2
הונג קונג	asia-east2
ג'קארטה	asia-southeast2
מלבורן	australia-southeast2
מומבאי	asia-south1
אוסקה	asia-northeast2
סיאול	asia-northeast3
סינגפור	asia-southeast1
סידני	australia-southeast1
טייוואן	asia-east1
טוקיו	asia-northeast1

בטבלה הבאה מפורטים האזורים באירופה שבהם BigQuery זמין.

תיאור האזור	שם האזור	פרטים
בלגיה	europe-west1	‫ רמה נמוכה של CO2‎
ברלין	europe-west10
פינלנד	europe-north1	‫ רמה נמוכה של CO2‎
פרנקפורט	europe-west3
לונדון	europe-west2	‫ רמה נמוכה של CO2‎
מדריד	europe-southwest1	‫ רמה נמוכה של CO2‎
מילאנו	europe-west8
הולנד	europe-west4	‫ רמה נמוכה של CO2‎
פריז	europe-west9	‫ רמה נמוכה של CO2‎
שטוקהולם	europe-north2	‫ רמה נמוכה של CO2‎
טורינו	europe-west12	‫ רמה נמוכה של CO2‎
ורשה	europe-central2	‫ רמה נמוכה של CO2‎
ציריך	europe-west6	‫ רמה נמוכה של CO2‎

בטבלה הבאה מפורטים האזורים במזרח התיכון שבהם BigQuery זמין.

תיאור האזור	שם האזור	פרטים
דמאם	me-central2
דוחה	me-central1
תל אביב	me-west1

בטבלה הבאה מפורטים האזורים באפריקה שבהם BigQuery זמין.

תיאור האזור	שם האזור	פרטים
יוהנסבורג	africa-south1

במספר אזורים

הערה: בהמשך השנה, BigQuery יפסיק להשתמש במונח multi-region. במקום זאת, שמות האזורים US ו-EU ייכללו ברשימת האזורים הבודדים, וימוקמו יחד עם האזורים us-central1 ו-europe-west4 בהתאמה. אין שינוי במיקום אחסון הנתונים הקיים.

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

תיאור של המיקום "במספר אזורים"	השם של המיקום "במספר אזורים"
מרכזי נתונים במדינות החברות באיחוד האירופי^1	EU
מרכזי נתונים בארצות הברית^2	US

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

‫¹ נתונים שנמצאים במיקום "במספר אזורים" של EU מאוחסנים רק באחד מהמיקומים הבאים: europe-west1 (בלגיה) או europe-west4 (הולנד). המיקום המדויק שבו הנתונים מאוחסנים ומעובדים נקבע באופן אוטומטי על ידי BigQuery.

‫² נתונים שנמצאים במיקום "במספר אזורים" של US מאוחסנים רק באחד מהמיקומים הבאים: us-central1 (איווה), us-west1 (אורגון) או us-central2 (אוקלהומה). המיקום המדויק שבו הנתונים מאוחסנים ומעובדים נקבע באופן אוטומטי על ידי BigQuery.

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

• במאמר יצירת קובצי snapshot של טבלאות באמצעות שאילתה מתוזמנת מופיעה דוגמה לשאילתה מתוזמנת שמשתמשת בחשבון שירות וכוללת את הפרמטרים @run_date ו-@run_time.