התראות על הפעלת שירות העברת נתונים ל-BigQuery

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

יש שני סוגים של התראות על הפעלה שאפשר להגדיר בשירות העברת הנתונים ל-BigQuery:

התראות Pub/Sub: התראות שניתנות לקריאה על ידי מכונה ונשלחות כשריצת העברה מסתיימת בהצלחה או נכשלת
התראות באימייל: התראות שקל לקרוא ושנשלחות כשריצת העברה נכשלת

אפשר להגדיר כל סוג בנפרד, או להשתמש בהתראות על הפעלת Pub/Sub ואימייל.

התראות Pub/Sub

התראות Pub/Sub משמשות לשליחת מידע על הפעלות העברה לנושא Pub/Sub. התראות Pub/Sub מופעלות על ידי הפעלות העברה שהסתיימו במצבים הבאים:

SUCCEEDED
FAILED
CANCELLED

אפשר לשלוח התראות לכל נושא Pub/Sub בכל פרויקט שבו יש לכם את ההרשאות המתאימות. אחרי שההודעות מתקבלות בנושא ה-Pub/Sub, אפשר לשלוח את ההודעה שמתקבלת לכל מספר של אפליקציות רשומות לנושא.

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

לפני שמגדירים התראות על הפעלת העברה ב-Pub/Sub, צריך:

להפעיל את ממשק ה-API של Pub/Sub בשביל הפרויקט שיקבל התראות.

הפעלת ה-API
לוודא שיש לכם את ההרשאות המתאימות בפרויקט שיקבל התראות:
- אם אתם הבעלים של הפרויקט שיקבל התראות, סביר להניח שיש לכם את ההרשאה הנדרשת.
- אם אתם מתכננים ליצור נושאים לקבלת התראות, צריכות להיות לכם הרשאות pubsub.topics.create.
- בין שאתם מתכננים להשתמש בנושאים חדשים או בנושאים קיימים, צריכות להיות לכם ההרשאות pubsub.topics.getIamPolicy ו-pubsub.topics.setIamPolicy. אם אתם יוצרים נושא, בדרך כלל תהיה לכם כבר הרשאה לצורך כך. לתפקיד המוגדר מראש הבא ב-IAM יש את ההרשאות pubsub.topics.getIamPolicy ו-pubsub.topics.setIamPolicy: pubsub.admin. מידע נוסף זמין במאמר בקרת גישה ב-Pub/Sub.
לוודא שיש לכם נושא Pub/Sub שאליו אתם רוצים לשלוח התראות.

פורמט ההתראות

ההתראות שנשלחות לנושא Pub/Sub כוללות שני חלקים:

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

מאפיינים

המאפיינים הם צמדי מפתח/ערך שכלולים בכל ההתראות שנשלחות משירות העברת נתונים ל-BigQuery לנושא Pub/Sub. ההתראות תמיד כוללות את הקבוצה הבאה של צמדי מפתח/ערך, בלי קשר למטען הייעודי (Payload) של ההתראה:

שם המאפיין	דוגמה	תיאור
eventType	`TRANSFER_RUN_FINISHED`	סוג האירוע שהתרחש. הערך האפשרי היחיד הוא `TRANSFER_RUN_FINISHED`.
payloadFormat	`JSON_API_V1`	הפורמט של המטען הייעודי (Payload) של האובייקט. הערך האפשרי היחיד הוא `JSON_API_V1`.

Payload

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

סוג המטען הייעודי (Payload)	תיאור
JSON_API_V1	המטען הייעודי (Payload) יהיה מחרוזת בפורמט JSON בתקן UTF-8 שתכיל את ייצוג המשאב של `TransferRun`.

התראות באימייל

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

אם השתמשתם בחשבון שירות כדי לאמת את הגדרת ההעברה, יכול להיות שלא תהיה לכם גישה לאימייל כדי לקבל התראות באימייל על הפעלת ההעברה. במקרים כאלה, מומלץ להגדיר התראות Pub/Sub כדי לקבל התראות על הפעלת ההעברה.

כדי לשלוח התראות באימייל על הפעלת העברה ליותר משתמשים, צריך להגדיר כללי העברת אימייל כדי להפיץ את ההודעות. אם אתם משתמשים ב-Gmail, אתם יכולים להעביר הודעות מ-Gmail לחשבון אחר באופן אוטומטי.

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

From: bigquery-data-transfer-service-noreply@google.com
To: TRANSFER_ADMIN
Title: BigQuery Data Transfer Service — Transfer Run Failure —
DISPLAY_NAME

Transfer Configuration
Display Name: DISPLAY_NAME
Source: DATA_SOURCE
Destination: PROJECT_ID

Run Summary
Run: RUN_NAME
Schedule Time: SCHEDULE_TIME
Run Time: RUN_TIME
View Run History

Google LLC 1600 Amphitheatre Parkway, Mountain View, CA 94043

This email was sent because you indicated you are willing to receive Run
Notifications from the BigQuery Data Transfer Service. If you do not wish to
receive such emails in the future, click View Transfer Configuration and
un-check the "Send E-mail Notifications" option.

הפעלה או עריכה של ההתראות

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

המסוף

נכנסים לדף BigQuery במסוף Google Cloud .

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

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 get run notification
public class RunNotification {

  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 pubsubTopicName = "MY_TOPIC_NAME";
    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")
            .setNotificationPubsubTopic(pubsubTopicName)
            .build();
    runNotification(projectId, transferConfig);
  }

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

Python

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