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

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

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

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

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

חיסכון בזמן ובמאמץ: באמצעות מאגרי פרוטוקולים, מגדירים את מבנה הנתונים פעם אחת בקובץ proto, ואז משתמשים בקוד המקור שנוצר כדי לכתוב את הנתונים ולקרוא אותם.
שיפור העקביות של הנתונים: באמצעות קובץ proto כמקור אמת יחיד, אפשר לוודא שכל האפליקציות והשירותים משתמשים באותו מודל נתונים.
מבטל כפילויות של נתונים: אפשר להשתמש ב-Protocol Buffers בפרויקטים שונים על ידי הגדרת סוגי הודעות בקובצי 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

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

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

יצירת קבוצה של מתארי קובץ 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 שיצרתם בקטע Generate a protobuf file descriptor set במסמך הזה. גודל הקובץ לא יכול להיות גדול מ-4 MB.
לוחצים על יצירה.

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

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

כדי ליצור חבילת סכימות, משתמשים בשיטה 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

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

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

gcloud

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

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

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

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

Java

כדי לראות רשימה של כל חבילות הסכימות בטבלה, משתמשים בשיטה 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 במסמכי התיעוד של protobuf.

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

המסוף

במסוף Google Cloud , פותחים את רשימת מופעי Bigtable.

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

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 חבילות סכימה לכל טבלה.
הגודל הכולל של תיאורי מאגר אחסון לפרוטוקולים שסודרו בסדר מסוים בחבילת סכימות לא יכול להיות יותר מ-4 MB. אין הגבלה ישירה על מספר הסכימות הנפרדות שאפשר לכלול בחבילה, כל עוד הגודל הכולל של החבילה לא חורג מהמגבלה הזו.

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

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

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

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

יצירת קבוצה של מתארי קובץ protobuf

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

המסוף

gcloud

Java

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

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

המסוף

gcloud

Java

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

המסוף

gcloud

Java

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

המסוף

gcloud

Java

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

המסוף

gcloud

Java

מגבלות

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