‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

יצירה וניהול של סכימות Protobuf

במאמר הזה מוסבר איך ליצור חבילות סכימות ולבצע בהן פעולות.

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

היתרונות של שימוש בחבילות סכימות:

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

התהליך של שימוש בסכימות ב-Bigtable מתחיל בקובצי ה-‎.proto. קובץ ‎.proto הוא קובץ טקסט שבו מגדירים את מבנה הנתונים. אתם משתמשים בכלי המקמפל של protobuf, שנקרא גם protoc, כדי ליצור קבוצה של מתארי קובצי protobuf, שהיא פורמט קריא למכונה של קובץ ה-proto. לאחר מכן, משתמשים בקבוצת המתארים הזו כדי ליצור חבילת סכימה.

בקטע נתונים לדוגמה מופיעות דוגמאות לקובצי ‎.proto ולקבוצות התיאורים התואמות שלהם.

בתרשים הבא מוצג תהליך השימוש בסכימות ב-Bigtable:

תהליך השימוש בסכימות protobuf ב-Bigtable. — **תרשים 1.** תהליך השימוש בסכימות של protobuf ב-Bigtable (אפשר ללחוץ כדי להגדיל).

**תרשים 1.** תהליך השימוש בסכימות של protobuf ב-Bigtable (אפשר ללחוץ כדי להגדיל).

אפשר ליצור חבילות סכימות באמצעות מסוף Google Cloud או Google Cloud CLI. אחרי שמעלים חבילת סכימה ל-Bigtable, אפשר לשלוח שאילתות לנתונים באמצעות הכלי ליצירת שאילתות של Bigtable Studio,‏ GoogleSQL ל-Bigtable או טבלאות חיצוניות של Bigtable ב-BigQuery.

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

אם אתם מתכננים להשתמש ב-CLI של gcloud, בצעו את השלבים הבאים:

מתקינים את Google Cloud CLI.
מאתחלים את ה-CLI של gcloud:
```
gcloud init
```

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות ליצירה ולניהול של חבילות סכימות, צריך לבקש מהאדמין להקצות לכם את התפקיד אדמין של Bigtable (roles/bigtable.admin) בניהול זהויות והרשאות גישה (IAM) בטבלה.

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

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

bigtable.schemaBundles.create
bigtable.schemaBundles.update
bigtable.schemaBundles.delete
bigtable.schemaBundles.get
bigtable.schemaBundles.list

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

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

יצירת קבוצה של תיאורי קבצים ב-protobuf

כדי ליצור חבילת סכימות, צריך ליצור קבוצת מתארים מקובצי ה-‎.proto באמצעות כלי המהדר של protobuf.

כדי להתקין את המהדר, מורידים את החבילה ופועלים לפי ההוראות בקובץ README.
מריצים את הקומפיילר:
```
protoc --proto_path=IMPORT_PATH --include_imports \
   --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTO
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫IMPORT_PATH: הספרייה שבה המהדר של protoc מחפש קובצי proto.
- ‫DESCRIPTOR_OUTPUT_LOCATION: הספרייה שבה המהדר של protoc שומר את קבוצת התיאורים שנוצרה.
- ‫PATH_TO_PROTO: הנתיב לקובץ ה-proto.

לדוגמה, כדי ליצור קבוצת מתארים בשם library.pb לקובץ library.proto בספרייה הנוכחית, אפשר להשתמש בפקודה הבאה:

protoc --include_imports --descriptor_set_out=library.pb
library.proto

יצירת חבילת סכימות

המסוף

במסוף Google Cloud , פותחים את רשימת המכונות של Bigtable.

פתיחת רשימת המכונות
בוחרים מכונה מהרשימה.
בחלונית הניווט, לוחצים על Bigtable Studio.
בחלונית Explorer, לצד הטבלה שבה רוצים ליצור חבילת סכימות, לוחצים על תפריט הפעולות more_vert ואז על Create schema bundle.
בתיבת הדו-שיח Create schema bundle, בשדה Schema Bundle ID, מזינים מזהה ייחודי לחבילת הסכימות.

המזהה צריך להיות באורך של 1 עד 50 תווים, והוא יכול להכיל רק אותיות, מספרים, קווים תחתונים ומקפים. הוא לא יכול להתחיל במקף ולא יכול להכיל את תו הנקודה (.).
בשדה File Descriptor Set (.pb file), לוחצים על Browse כדי לבחור את קבוצת תיאורי הקבצים של protobuf שיצרתם בקטע יצירת קבוצת תיאורי קבצים של protobuf במסמך הזה. גודל הקובץ לא יכול להיות יותר מ-4MB.
לוחצים על יצירה.

חבילת הסכימה נפתחת בכרטיסייה חדשה.

gcloud

כדי ליצור חבילת סכימה, משתמשים בפקודה gcloud bigtable schema-bundles create:

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

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

‫SCHEMA_BUNDLE_ID: מזהה ייחודי לחבילת הסכימה החדשה, שלא יכול להכיל נקודות (".").
‫INSTANCE_ID: המזהה של המכונה שבה יוצרים את חבילת הסכימה.
‫TABLE_ID: המזהה של הטבלה שבה יוצרים את חבילת הסכימה.
‫PROTO_DESCRIPTORS_FILE: הנתיב לקבוצת התיאורים שיצרתם בקטע יצירת קבוצה של תיאורי קובצי protobuf במסמך הזה.

Java

כדי ליצור חבילת סכימות, משתמשים ב-method‏ createSchemaBundle:

במאמר ספריות הלקוח של Bigtable מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Bigtable.

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

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .setSchemaBundleId(schemaBundleId)
          .setSchemaBundle(schemaBundleObj)
          .build();
  SchemaBundle schemaBundle = adminClient.createSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to create a schema bundle: " + e.getMessage());
}

מידע על חבילות סכימה

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

קבלת הגדרה של חבילת סכימה

המסוף

במסוף Google Cloud , פותחים את רשימת המכונות של Bigtable.

פתיחת רשימת המכונות
בוחרים מכונה מהרשימה.
בחלונית הניווט, לוחצים על Bigtable Studio.
בחלונית Explorer, מרחיבים את הטבלה שמכילה את חבילת הסכימה ואז מרחיבים את Schema Bundles.
לוחצים על חבילת הסכימות שרוצים לראות, או על תפריט הפעולות more_vert ליד חבילת הסכימות, ואז על View details.

נפתחת כרטיסייה שבה מוצגת ההגדרה של חבילת הסכימה.
אופציונלי: כדי לפתוח כרטיסייה של עורך שאילתות SQL עם שאילתה לדוגמה שמשתמשת בחבילת הסכימה, לוחצים על תפריט הפעולות more_vert לצד חבילת הסכימה ואז על Sample query.

gcloud

כדי לקבל פרטים על חבילת סכימות, משתמשים בפקודה gcloud bigtable schema-bundles describe:

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

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

‫SCHEMA_BUNDLE_ID: המזהה של חבילת הסכימה.
‫INSTANCE_ID: מזהה המכונה.
‫TABLE_ID: מזהה הטבלה.

Java

כדי לקבל את ההגדרה של חבילת סכימה, משתמשים ב-method‏ getSchemaBundle. השיטה הזו מחזירה אובייקט SchemaBundle שמכיל את הגדרת הסכימה.

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

במאמר ספריות הלקוח של Bigtable מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Bigtable.

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

SchemaBundle schemaBundle = null;
try {
  schemaBundle =
      adminClient.getSchemaBundle(
          "projects/"
              + projectId
              + "/instances/"
              + instanceId
              + "/tables/"
              + tableId
              + "/schemaBundles/"
              + schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(
          schemaBundle.getProtoSchema().getProtoDescriptors());

  System.out.println("--------- Deserialized FileDescriptorSet ---------");
  for (DescriptorProtos.FileDescriptorProto fileDescriptorProto :
      fileDescriptorSet.getFileList()) {
    System.out.println("File: " + fileDescriptorProto.getName());
    System.out.println("  Package: " + fileDescriptorProto.getPackage());
    for (DescriptorProtos.DescriptorProto messageType :
        fileDescriptorProto.getMessageTypeList()) {
      System.out.println("  Message: " + messageType.getName());
    }
  }
  System.out.println("--------------------------------------------------");
} catch (InvalidProtocolBufferException e) {
  System.err.println("Failed to parse FileDescriptorSet: " + e.getMessage());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to retrieve metadata from a non-existent schema bundle: " + e.getMessage());
}

הפלט אמור להיראות כך:

--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------

הצגת חבילות סכימה בטבלה

המסוף

במסוף Google Cloud , פותחים את רשימת המכונות של Bigtable.

פתיחת רשימת המכונות
בוחרים מכונה מהרשימה.
בחלונית הניווט, לוחצים על Bigtable Studio.
בחלונית Explorer, מרחיבים את הטבלה שמכילה את חבילות הסכימה שרוצים להציג.
מרחיבים את האפשרות Schema Bundles.

מופיעה רשימה של חבילות הסכימות בטבלה. אם בטבלה אין חבילות סכימה, הרשימה Schema Bundles לא מוצגת.

gcloud

כדי לראות רשימה של חבילות סכימה של טבלה, משתמשים בפקודה gcloud bigtable schema-bundles list:

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

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

‫INSTANCE_ID: מזהה המכונה.
‫TABLE_ID: מזהה הטבלה.

Java

כדי לראות רשימה של כל חבילות הסכימות בטבלה, משתמשים ב-method‏ listSchemaBundles. השיטה הזו מחזירה רשימה של מזהי חבילות סכימה.

בדוגמה הבאה אפשר לראות איך מציגים את חבילות הסכימה בטבלה:

במאמר ספריות הלקוח של Bigtable מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Bigtable.

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

List<String> schemaBundleIds = new ArrayList<>();
try {
  ListSchemaBundlesRequest request =
      ListSchemaBundlesRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .build();
  for (SchemaBundle bundle : adminClient.listSchemaBundles(request).iterateAll()) {
    String id = SchemaBundleName.parse(bundle.getName()).getSchemaBundle();
    System.out.println(id);
    schemaBundleIds.add(id);
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to list schema bundles from a non-existent table: " + e.getMessage());
}

הפלט אמור להיראות כך:

my-schema-bundle-1
my-schema-bundle-2

עדכון של חבילת סכימה

כשמעדכנים חבילת סכימות, Bigtable בודק אם קבוצת התיאורים החדשה תואמת לדורות קודמים של הקבוצה הקיימת. אם Bigtable מזהה חוסר תאימות, העדכון נכשל ומוצגת השגיאה FailedPrecondition. מומלץ לשמור את מספרי השדות שנמחקו כדי למנוע שימוש חוזר בהם. למידע נוסף, קראו את המאמר Proto Best Practices במסמכי התיעוד של protobuf.

אם אתם בטוחים שהשינויים הלא תואמים בטוחים ואתם רוצים לאלץ עדכון, אתם יכולים להשתמש בדגל --ignore-warnings עם ה-CLI של gcloud. עם זאת, אי אפשר לאלץ שינויים לא תואמים אם חבילת הסכימה נמצאת בשימוש על ידי תצוגה מהותית רציפה או תצוגה לוגית. התצוגות מסתמכות על הגדרות ההודעות של חבילת הסכימה כדי לנתח נתונים ולבצע שאילתות, ולכן שינויים לא תואמים יגרמו לשגיאות בשאילתות בתצוגות לוגיות, ולכשלים בתצוגות המהותיות הרציפות במהלך עיבוד הנתונים. כדי לבצע שינויים שלא תואמים לדורות קודמים בחבילת סכימות שתצוגה מפנה אליה, קודם צריך לעדכן או למחוק את התצוגות שמפנות אליה.

המסוף

במסוף Google Cloud , פותחים את רשימת המכונות של Bigtable.

פתיחת רשימת המכונות
בוחרים מכונה מהרשימה.
בחלונית הניווט, לוחצים על Bigtable Studio.
בחלונית Explorer, מרחיבים את הטבלה שמכילה את חבילת הסכימה ואז מרחיבים את Schema Bundles.
לצד חבילת הסכימות שרוצים לעדכן, לוחצים על תפריט הפעולות more_vert ואז על Update.
בתיבת הדו-שיח Update schema bundle, בשדה File Descriptor Set (.pb file), בוחרים את קבוצת תיאורי הקבצים החדשה של protobuf. גודל הקובץ לא יכול להיות יותר מ-4MB.
לוחצים על Save.

gcloud

כדי לעדכן חבילת סכימה כך שתשתמש בקבוצת מתארים אחרת, משתמשים בפקודה gcloud bigtable schema-bundles update:

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

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

‫SCHEMA_BUNDLE_ID: המזהה של חבילת הסכימות שרוצים לעדכן.
‫INSTANCE_ID: המזהה של המכונה שמכילה את חבילת הסכימה.
‫TABLE_ID: מזהה הטבלה שמכילה את חבילת הסכימה.
‫PROTO_DESCRIPTORS_FILE: הנתיב לקובץ החדש של קבוצת התיאורים.

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

Java

במאמר ספריות הלקוח של Bigtable מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Bigtable.

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

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setName(
              "projects/"
                  + projectId
                  + "/instances/"
                  + instanceId
                  + "/tables/"
                  + tableId
                  + "/schemaBundles/"
                  + schemaBundleId)
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.newBuilder()
          .setSchemaBundle(schemaBundleObj)
          .setUpdateMask(FieldMask.newBuilder().addPaths("proto_schema").build())
          .build();
  SchemaBundle schemaBundle = adminClient.updateSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to modify schema bundle: " + e.getMessage());
}

מחיקת חבילת סכימות

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

המסוף

במסוף Google Cloud , פותחים את רשימת המכונות של Bigtable.

פתיחת רשימת המכונות
בוחרים מכונה מהרשימה.
בחלונית הניווט, לוחצים על Bigtable Studio.
בחלונית Explorer, מרחיבים את הטבלה שמכילה את חבילת הסכימה ואז מרחיבים את Schema Bundles.
ליד חבילת הסכימות שרוצים למחוק, לוחצים על תפריט הפעולות more_vert ואז על Delete.
בתיבת הדו-שיח לאישור, לוחצים על מחיקה.

gcloud

כדי למחוק חבילת סכימות, מפעילים את הפקודה gcloud bigtable schema-bundles delete:

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

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

‫SCHEMA_BUNDLE_ID: המזהה של חבילת הסכימה שרוצים למחוק.
‫INSTANCE_ID: המזהה של המכונה שמכילה את חבילת הסכימה.
‫TABLE_ID: מזהה הטבלה שמכילה את חבילת הסכימה.

Java

במאמר ספריות הלקוח של Bigtable מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Bigtable.

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

try {
  adminClient.deleteSchemaBundle(
      "projects/"
          + projectId
          + "/instances/"
          + instanceId
          + "/tables/"
          + tableId
          + "/schemaBundles/"
          + schemaBundleId);
  System.out.printf("SchemaBundle: %s deleted successfully%n", schemaBundleId);
} catch (NotFoundException e) {
  System.err.println("Failed to delete a non-existent schema bundle: " + e.getMessage());
}

מגבלות

לחבילות סכימה יש את המגבלות הבאות:

אפשר ליצור עד 10 חבילות סכימה לכל טבלה. המגבלה הזו חלה גם על חבילות סכימות של protobuf וגם על חבילות סכימות של Avro.
הגודל הכולל של מתארי מאגר האחסון לפרוטוקולים שעברו סריאליזציה בתוך חבילת סכימה לא יכול להיות יותר מ-4MB. אין הגבלה ישירה על מספר הסכימות הנפרדות שאפשר לכלול בחבילה, כל עוד הגודל הכולל של החבילה לא חורג מהמגבלה הזו.

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

איך שולחים שאילתות לנתוני protobuf
איך יוצרים ומנהלים סכימות של Avro
מידע על שאילתות משתנות או לא ודאיות
אפשר לקרוא מידע נוסף במאמר סקירה כללית של GoogleSQL ל-Bigtable.