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

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

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

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

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

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

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

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

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

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

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

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

  1. מתקינים את Google Cloud CLI.

  2. מאתחלים את ה-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.

  1. כדי להתקין את הקומפיילר, מורידים את החבילה ופועלים לפי ההוראות בקובץ ה-README.

  2. מריצים את הקומפיילר:

    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

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

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: הנתיב לערכת התיאורים שנוצרה בשלב הקודם.

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

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

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
--------------------------------------------------

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

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

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

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());
}

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

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

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