REST Resource: iceberg.v1.restcatalog.extensions.projects.catalogs

משאב: IcebergCatalog

המידע על קטלוג REST של Iceberg.

ייצוג ב-JSON 
{
  "name": string,
  "credential-mode": enum (CredentialMode),
  "biglake-service-account": string,
  "biglake-service-account-id": string,
  "catalog-type": enum (CatalogType),
  "default-location": string,
  "storage-regions": [
    string
  ],
  "create-time": string,
  "update-time": string,
  "replicas": [
    {
      object (Replica)
    }
  ],
  "description": string,
  "restricted-locations-config": {
    object (RestrictedLocationsConfig)
  },
  "federated-catalog-options": {
    object (FederatedCatalogOptions)
  },
  "cross-cloud-cache-options": {
    object (CrossCloudCacheOptions)
  },
  "encryption-config": {
    object (EncryptionConfig)
  }
}
שדות
name

string

מזהה. שם הקטלוג, projects/my-project/catalogs/my-catalog. אי אפשר לשנות את התוכן של השדה הזה. המערכת מתעלמת מהשדה הזה בשיטה catalogs.create.
credential-mode

enum (CredentialMode)

זה שינוי אופציונלי. מצב פרטי הכניסה של הקטלוג.
biglake-service-account

string

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

בקטלוגים מאוחדים, חשבון השירות תמיד יוקצה והוא ישמש לגישה לקטלוג המרוחק לצורך רענון מטא-נתונים ברקע. אם הערך של google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.IdentityMode הוא IDENTITY_MODE_SERVICE_IDENTITY, הוא ישמש גם לשאילתות.
biglake-service-account-id

string

פלט בלבד. המזהה הייחודי של חשבון השירות. המאפיין הזה משמש בתרחישים של איחוד.
catalog-type

enum (CatalogType)

חובה. סוג הקטלוג. נדרש ל-catalogs.create. סוג הקטלוג הוא קבוע, למעט במקרה של המרה מ-CATALOG_TYPE_GCS_BUCKET ל-CATALOG_TYPE_BIGLAKE.
default-location

string

זה שינוי אופציונלי. מיקום האחסון שמוגדר כברירת מחדל לקטלוג, למשל gs://my-bucket. בקטלוגים של קטגוריות ב-Google Cloud Storage, זהו פלט בלבד.

בקטלוגים של BigLake, חובה לספק את השדה הזה, והוא צריך להצביע על קטגוריה של Google Cloud Storage או על נתיב בתוך הקטגוריה הזו. הנתיב הזה משמש כספריית הבסיס ליצירת הנתיב המלא לספריות הנתונים והמטא-נתונים של טבלה, כשלא מציינים מיקום ברמת מרחב השמות או הטבלה. הנתיב המלא נוצר על ידי הוספת מרחב השמות ומזהי הטבלה למיקום ברירת המחדל.
storage-regions[]

string

פלט בלבד. האזורים ב-GCP של הקטגוריה במיקום ברירת המחדל, למשל us-central1, nam4 או us. העמודה הזו תכיל ערך אחד לכל המיקומים, למעט קטלוגים שמוגדרים לשימוש בקטגוריות מותאמות אישית בשני אזורים. במקרה כזה, העמודה תכיל את שני האזורים של הקטגוריה. האזורים בשדה הזה צריכים להיות בתחום השיפוט של המיקום הראשי של הקטלוג או בקרבתו.
create-time

string (Timestamp format)

פלט בלבד. התאריך שבו נוצר הקטלוג.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
update-time

string (Timestamp format)

פלט בלבד. מתי הקטלוג עודכן לאחרונה.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
replicas[]

object (Replica)

פלט בלבד. העותקים המשוכפלים של המטא-נתונים של הקטלוג.
description

string

זה שינוי אופציונלי. תיאור של הקטלוג שסופק על ידי המשתמש. התיאור צריך להיות מחרוזת UTF-8 באורך של עד 1,024 תווים.
restricted-locations-config

object (RestrictedLocationsConfig)

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

אם השדה הזה לא מוגדר או אם restrictedLocationsConfig.restricted_locations ריק, מותרים כל המיקומים שאפשר לגשת אליהם. אם restrictedLocationsConfig.restricted_locations לא ריק, מותרים רק מיקומים ב-defaultLocation וב-restrictedLocationsConfig.restricted_locations.
federated-catalog-options

object (FederatedCatalogOptions)

זה שינוי אופציונלי. אפשרויות הגדרה לקטלוגים מאוחדים.
cross-cloud-cache-options

object (CrossCloudCacheOptions)

זה שינוי אופציונלי. אפשרויות הגדרה של שמירת נתונים וקובצי מטא-נתונים במטמון חוצה-עננים (cross-cloud).
encryption-config

object (EncryptionConfig)

זה שינוי אופציונלי. הגדרת הצפנה בהתאמה אישית (למשל, מפתחות Cloud KMS).

CredentialMode

מצב ההרשאה שמשמש לקטלוג.

טיפוסים בני מנייה (enum)
CREDENTIAL_MODE_UNSPECIFIED ערך ברירת המחדל או ערך לא מוגדר. הערך הזה לא בשימוש.
CREDENTIAL_MODE_END_USER מצב פרטי הכניסה של משתמש הקצה, ברירת מחדל. למשתמש המבצע את האימות צריכה להיות גישה למשאבי הקטלוג ולאובייקטים הבסיסיים של Google Cloud Storage.
CREDENTIAL_MODE_VENDED_CREDENTIALS

מצב מכירת פרטי כניסה. למשתמש המבצע את האימות נדרשת גישה רק למשאבי הקטלוג, והמערכת תספק לקורא פרטי כניסה עם היקף הרשאות מצומצם כדי לגשת לאובייקטים של Google Cloud Storage. כל הפעולות בטבלה במצב הזה מחייבות שהכותרת X-Iceberg-Access-Delegation תוגדר כ-vended-credentials. המערכת תיצור חשבון שירות ב-google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account, שאדמין הקטלוג צריך לתת לו גישה לאובייקט ב-Google Cloud Storage.

פרטים נוספים זמינים בכתובת https://docs.cloud.google.com/lakehouse/docs/credential-vending.

CatalogType

קובע את סוג הקטלוג.

טיפוסים בני מנייה (enum)
CATALOG_TYPE_UNSPECIFIED ערך ברירת המחדל או ערך לא מוגדר. הערך הזה לא בשימוש.
CATALOG_TYPE_GCS_BUCKET סוג הקטלוג של קטגוריה ב-Google Cloud Storage.
CATALOG_TYPE_BIGLAKE סוג הקטלוג של BigLake.
CATALOG_TYPE_FEDERATED סוג הקטלוג המאוחד.

רפליקה

העתק של הקטלוג.

ייצוג ב-JSON 
{
  "region": string,
  "state": enum (State)
}
שדות
region

string

פלט בלבד. האזור של העותק. לדוגמה, us-east1
state

enum (State)

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

מדינה

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

טיפוסים בני מנייה (enum)
STATE_UNKNOWN ערך ברירת המחדל או ערך לא מוגדר. הערך הזה לא בשימוש.
STATE_PRIMARY העותק הוא העותק הראשי שאפשר לכתוב בו.
STATE_PRIMARY_IN_PROGRESS העותק המשוכפל הוגדר לאחרונה כראשי, אבל עדיין אי אפשר לכתוב בכל מרחבי השמות.
STATE_SECONDARY הרפליקה היא רפליקה משנית לקריאה בלבד.

RestrictedLocationsConfig

הגדרת הגבלות על מיקום.

ייצוג ב-JSON 
{
  "restricted-locations": [
    string
  ]
}
שדות
restricted-locations[]

string

זה שינוי אופציונלי. קטגוריות ומיקומים נוספים ב-Google Cloud Storage (לדוגמה, gs://my-other-bucket/...) שמותר למשאבים בקטלוג להשתמש בהם. השדה הזה משמש כרגע רק לקטלוגים של BigLake.

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

EncryptionConfig

הגדרת הצפנה בהתאמה אישית (למשל, מפתחות Cloud KMS).

ייצוג ב-JSON 
{
  "kms-key-name": string
}
שדות
kms-key-name

string

זה שינוי אופציונלי. שם מפתח Cloud KMS שמשמש להצפנת נתונים במטמון שאוחזרו מהקטלוג. פורמט: projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}

FederatedCatalogOptions

אפשרויות להגדרת קטלוג מאוחד.

ייצוג ב-JSON 
{
  "refresh-options": {
    object (RefreshOptions)
  },
  "refresh-status": {
    object (RefreshStatus)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "unity-catalog-info": {
    object (UnityCatalogInfo)
  },
  "glue-catalog-info": {
    object (GlueCatalogInfo)
  },
  "snowflake-catalog-info": {
    object (SnowflakeCatalogInfo)
  },
  "workday-catalog-info": {
    object (WorkdayCatalogInfo)
  }
  // End of mutually exclusive fields.
  "secret-name": string,
  "service-directory-name": string
}
שדות
refresh-options

object (RefreshOptions)

זה שינוי אופציונלי. רענון ההגדרות.
refresh-status

object (RefreshStatus)

פלט בלבד. הסטטוס של פעולות רענון המטא-נתונים ברקע.
מידע ספציפי על קטלוג REST מרוחק של Iceberg. הרשימה הבאה כוללת שדות שאי אפשר להשתמש בהם בו-זמנית. בכל תשובה יוגדר לכל היותר אחד מהשדות:
unity-catalog-info

object (UnityCatalogInfo)

זה שינוי אופציונלי. מידע שספציפי ל-Databricks Unity Catalog.
glue-catalog-info

object (GlueCatalogInfo)

זה שינוי אופציונלי. מידע שספציפי ל-AWS Glue Data Catalog.
snowflake-catalog-info

object (SnowflakeCatalogInfo)

זה שינוי אופציונלי. מידע שספציפי ל-Snowflake Horizon Catalog.
workday-catalog-info

object (WorkdayCatalogInfo)

זה שינוי אופציונלי. מידע שספציפי ל-Workday Data Lake.
סוף השדות הבלעדיים.
secret-name

string

זה שינוי אופציונלי. שם המשאב הסודי ב-Secret Manager, בפורמט projects/{projectId}/locations/{location}/secrets/{secret_id} או projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_id}.

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

השדה הזה לא בשימוש אם מוגדרים google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id או google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role.
service-directory-name

string

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

פורמט: projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}

הפרמטר הזה משמש שאילתות של BigQuery כדי לפתור נקודות קצה פרטיות לאחזור קובצי נתונים (למשל, נתוני Iceberg ב-S3 או ב-Azure Data Lake Storage) דרך חיבור לרשת פרטית כמו Cross-Cloud Interconnect.

UnityCatalogInfo

מידע שספציפי ל-Databricks Unity Catalog. נקודת הקצה של קטלוג REST של Iceberg היא בפורמט: https://<instanceName>/api/2.1/unity-catalog/iceberg-rest/v1/config?warehouse=<catalogName>.

ייצוג ב-JSON 
{
  "instance-name": string,
  "catalog-name": string,
  "service-principal-application-id": string
}
שדות
instance-name

string

חובה. אי אפשר לשנות. שם המופע של סביבת העבודה של Databricks. לדוגמה, בכתובת ה-URL של סביבת העבודה ב-Databricks‏ https://1.1.gcp.databricks.com, שם המופע הוא 1.1.gcp.databricks.com.
catalog-name

string

חובה. אי אפשר לשנות. השם של הקטלוג ב-Databricks Unity Catalog.
service-principal-application-id

string

זה שינוי אופציונלי. מזהה האפליקציה של חשבון המשתמש בשירות Databricks שמשמש לגישה ל-Databricks Unity Catalog בתהליך האימות של OIDC.

GlueCatalogInfo

מידע שספציפי ל-AWS Glue Data Catalog. נקודת הקצה של קטלוג REST של Iceberg היא בפורמט: https://glue.<awsRegion>.amazonaws.com/iceberg/v1/config?warehouse=<warehouse>.

ייצוג ב-JSON 
{
  "warehouse": string,
  "aws-region": string,
  "aws-role-arn": string
}
שדות
warehouse

string

חובה. אי אפשר לשנות. המיקום של מחסן הנתונים ב-AWS Glue Data Catalog.

בקטלוג חשבונות ברירת המחדל, משתמשים במזהה חשבון AWS בן 12 ספרות (לדוגמה, 111222333444). בקטגוריית טבלאות של Amazon S3, משתמשים בפורמט <account_id>:s3tablescatalog/<table_bucket_name> (לדוגמה, 111222333444:s3tablescatalog/my-table-bucket).
aws-region

string

חובה. אי אפשר לשנות. האזור ב-AWS של AWS Glue Data Catalog (לדוגמה, us-east-1). כדי לקבל את הביצועים הכי טובים, האזור של הקטלוג המאוחד צריך להיות באותו מיקום גיאוגרפי ובאותה סמכות שיפוט כמו האזור ב-AWS.
aws-role-arn

string

חובה. שם משאב Amazon‏ (ARN) של תפקיד AWS IAM שהקטלוג המאוחד מקבל כדי לגשת ל-AWS Glue Data Catalog.

SnowflakeCatalogInfo

מידע שספציפי ל-Snowflake Horizon Catalog. נקודת הקצה של קטלוג REST של Iceberg היא בפורמט: https://<accountIdentifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>.

ייצוג ב-JSON 
{
  "account-identifier": string,
  "warehouse": string,
  "snowflake-role": string
}
שדות
account-identifier

string

חובה. אי אפשר לשנות. מזהה החשבון ב-Snowflake. לדוגמה, בכתובת ה-URL של פריסת Snowflake‏ https://myorg-myaccount.snowflakecomputing.com, מזהה החשבון הוא myorg-myaccount.
warehouse

string

חובה. אי אפשר לשנות. השם של מסד הנתונים ב-Snowflake Horizon Catalog.
snowflake-role

string

זה שינוי אופציונלי. שם התפקיד ב-Snowflake שמשמש לגישה לקטלוג Snowflake Horizon בתהליך האימות של איחוד שירותי אימות הזהות של עומסי עבודה (OIDC).

WorkdayCatalogInfo

מידע שספציפי ל-Workday Data Lake. נקודת הקצה של קטלוג REST של Iceberg היא בפורמט: https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday.

ייצוג ב-JSON 
{
  "base-url": string,
  "tenant": string
}
שדות
base-url

string

חובה. אי אפשר לשנות. כתובת ה-URL הבסיסית של המכונה ב-Workday. לדוגמה, impl-services1.wd12.myworkday.com או wd501.myworkday.com.
tenant

string

חובה. אי אפשר לשנות. שם הדייר ב-Workday.

RefreshOptions

רענון ההגדרות.

ייצוג ב-JSON 
{
  "refresh-schedule": {
    object (RefreshSchedule)
  },
  "refresh-scope": {
    object (RefreshScope)
  }
}
שדות
refresh-schedule

object (RefreshSchedule)

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

object (RefreshScope)

זה שינוי אופציונלי. רענון של הגדרות היקף.

RefreshSchedule

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

ייצוג ב-JSON 
{
  "refresh-interval": string
}
שדות
refresh-interval

string (Duration format)

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

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-s. דוגמה: "3.5s".

RefreshScope

ההיקף מגדיר קבוצת משנה של מרחבי שמות לרענון.

ייצוג ב-JSON 
{
  "namespace-filters": [
    string
  ]
}
שדות
namespace-filters[]

string

זה שינוי אופציונלי. מסננים לקביעה אילו מרחבי שמות נכללים בתהליך הרענון. – רשימה ריקה פירושה שכל מרחבי השמות כלולים. ‫– [namespaces]: צריך לכלול את מרחבי השמות שצוינו. ‪['ns1', 'ns2'] : Discover only namespaces 'ns1' and 'ns2'.

RefreshStatus

סטטוס רענון המטא-נתונים ברקע של קטלוג מרוחק.

ייצוג ב-JSON 
{
  "start-time": string,
  "end-time": string,
  "status": {
    object (Status)
  }
}
שדות
start-time

string (Timestamp format)

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

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
end-time

string (Timestamp format)

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

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
status

object (Status)

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

CrossCloudCacheOptions

אפשרויות הגדרה של שמירת נתונים וקובצי מטא-נתונים במטמון חוצה-עננים (cross-cloud).

ייצוג ב-JSON 
{
  "enabled": boolean
}
שדות
enabled

boolean

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

אם הערך הזה הוא true, נתוני קריאה ומטא-נתונים מאוחסנים במטמון, מה שיכול לשפר את הביצועים ולהפחית את עלויות התעבורה היוצאת (egress) ברשת עבור שאילתות חוצות-ענן.

אם הערך הוא false, שמירה במטמון חוצה-עננים מושבתת.

Methods

create

 יוצר את קטלוג REST של Iceberg.

delete

 מחיקת קטלוג REST של Iceberg.

failover

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

get

 הפונקציה מחזירה את אפשרויות ההגדרה של קטלוג REST של Iceberg.

list

 מציג רשימה של קטלוגים של Iceberg REST.

patch

 מעדכנים את אפשרויות ההגדרה של קטלוג REST של Iceberg.