Package google.firestore.admin.v1

索引

Firestore 管理員

Cloud Firestore Admin API。

這個 API 為 Cloud Firestore 提供多項管理服務。

系統會依據 Google Cloud Firestore API 的定義使用專案、資料庫、命名空間、集合、集合群組和文件,

Operation:作業代表在背景執行的工作。

索引服務會管理 Cloud Firestore 索引。

索引建立作業會以非同步的方式執行。系統會為這類非同步作業建立 Operation 資源。可透過 Operation 資源查詢作業狀態 (包括發生的任何錯誤)。

「作業」集合會列出已對指定專案執行動作的記錄 (包括執行中的所有作業)。系統不會直接建立作業,而是透過呼叫其他集合或資源。

系統可能會刪除已完成的作業,停止將其列為作業集合的一部分。作業會在 30 天後垃圾收集。根據預設,ListOperations 只會傳回進行中和失敗的作業。如要列出已完成的作業,請使用篩選器 done: true 發出 ListOperations 要求。

作業是由服務 FirestoreAdmin 建立,但可透過服務 google.longrunning.Operations 存取。

建立備份排程

rpc CreateBackupSchedule(CreateBackupScheduleRequest) returns (BackupSchedule)

建立資料庫的備份排程。一個資料庫最多可以設定兩個備份排程,一個每日備份排程和一個每週備份排程。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

建立資料庫

rpc CreateDatabase(CreateDatabaseRequest) returns (Operation)

建立資料庫。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

CreateIndex

rpc CreateIndex(CreateIndexRequest) returns (Operation)

建立複合式索引。這會傳回 google.longrunning.Operation,可用於追蹤建立作業的狀態。該作業的中繼資料會是 IndexOperationMetadata 類型。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

刪除備份

rpc DeleteBackup(DeleteBackupRequest) returns (Empty)

刪除備份。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

刪除 BackupSchedule

rpc DeleteBackupSchedule(DeleteBackupScheduleRequest) returns (Empty)

刪除備份排程。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

刪除資料庫

rpc DeleteDatabase(DeleteDatabaseRequest) returns (Operation)

刪除資料庫。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

DeleteIndex

rpc DeleteIndex(DeleteIndexRequest) returns (Empty)

刪除複合式索引。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

匯出文件

rpc ExportDocuments(ExportDocumentsRequest) returns (Operation)

這個外掛程式能將 Google Cloud Firestore 中全部或部分文件的副本匯出至其他儲存系統,例如 Google Cloud Storage。最近的文件更新可能不會反映在匯出作業中。匯出作業會在背景中執行,並透過建立的 Operation 資源監控及管理進度。執行匯出作業的輸出內容後,才能使用這些輸出內容。如果匯出作業在完成前遭到取消,可能會導致部分資料無法在 Google Cloud Storage 中留存。

如要進一步瞭解匯出行為和輸出格式,請參閱:https://cloud.google.com/firestore/docs/manage-data/export-import

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

取得備份

rpc GetBackup(GetBackupRequest) returns (Backup)

取得備份的相關資訊。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

GetBackupSchedule

rpc GetBackupSchedule(GetBackupScheduleRequest) returns (BackupSchedule)

取得備份排程的相關資訊。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

取得資料庫

rpc GetDatabase(GetDatabaseRequest) returns (Database)

取得資料庫相關資訊。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

取得欄位

rpc GetField(GetFieldRequest) returns (Field)

取得欄位的中繼資料和設定。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

取得索引

rpc GetIndex(GetIndexRequest) returns (Index)

取得複合式索引。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

匯入文件

rpc ImportDocuments(ImportDocumentsRequest) returns (Operation)

將文件匯入 Google Cloud Firestore。名稱相同的現有文件將遭到覆寫。匯入作業會在背景中進行,並透過建立的 Operation 資源監控及管理其進度。如果 ImportDocuments 作業已取消,可能是因為部分資料已匯入 Cloud Firestore。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

列出備份排程

rpc ListBackupSchedules(ListBackupSchedulesRequest) returns (ListBackupSchedulesResponse)

列出備份排程。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

列出備份

rpc ListBackups(ListBackupsRequest) returns (ListBackupsResponse)

列出所有備份。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

列出資料庫

rpc ListDatabases(ListDatabasesRequest) returns (ListDatabasesResponse)

列出專案中的所有資料庫。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

列出欄位

rpc ListFields(ListFieldsRequest) returns (ListFieldsResponse)

列出這個資料庫的欄位設定和中繼資料。

目前,FirestoreAdmin.ListFields 僅支援已明確覆寫的資訊欄位。如要發出這項查詢,請呼叫 FirestoreAdmin.ListFields,並將篩選器設為 indexConfig.usesAncestorConfig:falsettlConfig:*

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

清單索引

rpc ListIndexes(ListIndexesRequest) returns (ListIndexesResponse)

列出複合式索引。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

還原資料庫

rpc RestoreDatabase(RestoreDatabaseRequest) returns (Operation)

從現有的備份還原,建立新資料庫。

新資料庫必須與現有備份位於相同雲端區域或多區域位置。運作方式與 [FirestoreAdmin.CreateDatabase][google.firestore.admin.v1.CreateDatabase] 類似,差別在於不必建立新的空白資料庫,而是建立新的資料庫,並採用資料庫類型、索引設定和現有備份中的文件。

long-running operation 可用來追蹤還原進度,且作業的 metadata 欄位類型為 RestoreDatabaseMetadata。如果還原成功,response 類型就是 Database。在 LRO 完成前,新的資料庫無法讀取或寫入。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

更新備份排程

rpc UpdateBackupSchedule(UpdateBackupScheduleRequest) returns (BackupSchedule)

更新備份排程。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

更新資料庫

rpc UpdateDatabase(UpdateDatabaseRequest) returns (Operation)

更新資料庫。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

更新欄位

rpc UpdateField(UpdateFieldRequest) returns (Operation)

更新欄位設定。欄位更新目前僅適用於單一欄位索引設定。不過,呼叫 FirestoreAdmin.UpdateField 時應提供欄位遮罩,避免變更呼叫端所不知道的任何設定。欄位遮罩應指定為:{ paths: "index_config" }

這項呼叫會傳回 google.longrunning.Operation,可用於追蹤欄位更新狀態。該作業的中繼資料會是 FieldOperationMetadata 類型。

如要為資料庫進行預設欄位設定,請使用特殊的 Field 並加上資源名稱:projects/{project_id}/databases/{database_id}/collectionGroups/__default__/fields/*

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

備份

Cloud Firestore 資料庫的備份。

備份包含指定資料庫在特定時間點的所有文件和索引設定。

欄位
name

string

僅供輸出。備份的專屬資源名稱。

格式為 projects/{project}/locations/{location}/backups/{backup}

database

string

僅供輸出。備份來源的 Firestore 資料庫名稱。

格式為 projects/{project}/databases/{database}

database_uid

string

僅供輸出。系統針對備份的來源 Firestore 資料庫產生的 UUID4。

snapshot_time

Timestamp

僅供輸出。備份目前含有外部一致的資料庫副本。

expire_time

Timestamp

僅供輸出。這項備份的到期時間。

state

State

僅供輸出。備份目前的狀態。

狀態

表示備份的目前狀態。

列舉
STATE_UNSPECIFIED 未指定狀態。
CREATING 仍在建立待處理的備份。在這個狀態下,系統會拒絕備份作業。
READY 備份完成,隨時可以使用。
NOT_AVAILABLE 目前無法使用備份,

備份排程

Cloud Firestore 資料庫的備份排程。

這項資源的擁有者為要備份的資料庫,會連同資料庫一起刪除。但不會實際備份。

欄位
name

string

僅供輸出。指定專案內所有位置和資料庫的專屬備份排程 ID。

系統會自動指派這個問題。

格式為 projects/{project}/databases/{database}/backupSchedules/{backup_schedule}

create_time

Timestamp

僅供輸出。這項備份排程的建立時間與生效時間的時間戳記。

在這個時間之前,系統不會為這項排程建立任何備份。

update_time

Timestamp

僅供輸出。這項備份排程最近一次更新時的時間戳記。備份排程首次建立時,這與 create_time 相同。

retention

Duration

與其建立時間相較,未來的相對時間應刪除備份,例如:將備份保留 7 天。

支援的保留期限最長為 14 週。

聯集欄位 recurrence。代表備份時間的其中一個欄位。recurrence 只能採用下列其中一種設定:
daily_recurrence

DailyRecurrence

用於每天執行的時間表。

weekly_recurrence

WeeklyRecurrence

計算在每週的特定日期執行的排程。

建立備份排程要求

FirestoreAdmin.CreateBackupSchedule 的要求。

欄位
parent

string

執行個體類型,父項資料庫。

格式化 projects/{project}/databases/{database}

backup_schedule

BackupSchedule

執行個體類型,要建立的備份排程。

CreateDatabaseMetadata

這個類型沒有任何欄位。

資料庫建立作業的相關中繼資料。

CreateDatabaseRequest

FirestoreAdmin.CreateDatabase 的要求。

欄位
parent

string

執行個體類型,表單 projects/{project_id} 的父項名稱

database

Database

執行個體類型,要建立的資料庫。

database_id

string

執行個體類型,用於資料庫的 ID,會成為資料庫資源名稱的最終元件。

此值長度應介於 4 至 63 個字元之間。有效的字元為 /[a-z][0-9]-/,開頭必須為英文字母,最後一個字母或數字。不得與 UUID 類似 /[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}/。

「(預設)」資料庫 ID 也有效

建立索引要求

FirestoreAdmin.CreateIndex 的要求。

欄位
parent

string

執行個體類型,表單 projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id} 的父項名稱

index

Index

執行個體類型,要建立的複合式索引。

每日重複週期

這個類型沒有任何欄位。

代表每天執行的週期性排程。

時區為世界標準時間 (UTC)。

資料庫

Cloud Firestore 資料庫。

欄位
name

string

資料庫的資源名稱。格式:projects/{project}/databases/{database}

uid

string

僅供輸出。系統為這個資料庫產生的 UUID4。

create_time

Timestamp

僅供輸出。建立這個資料庫時的時間戳記。2016 年之前建立的資料庫不會填入 create_time。

update_time

Timestamp

僅供輸出。這個資料庫最近一次更新時的時間戳記。請注意,這項資訊僅包含資料庫資源更新,不含資料庫包含的資料。

delete_time

Timestamp

僅供輸出。刪除這個資料庫的時間戳記。只有在刪除資料庫時才設定。

location_id

string

資料庫的位置。如需查看服務範圍,請參閱 https://cloud.google.com/firestore/docs/locations

type

DatabaseType

資料庫的類型。如要瞭解如何選擇,請參閱 https://cloud.google.com/datastore/docs/firestore-or-datastore

concurrency_mode

ConcurrencyMode

此資料庫要使用的並行控制模式。

version_retention_period

Duration

僅供輸出。過往資料版本保留在資料庫中的時間範圍。

任何 readquery 都可以在此視窗中指定 read_time,並讀取當時的資料庫狀態。

如果啟用時間點復原功能,保留期限為 7 天。否則,保留期限為 1 小時。

earliest_version_time

Timestamp

僅供輸出。從資料庫讀取舊版資料之最早的時間戳記。請參閱上方的 [version_retention_period];這個欄位會填入 now - version_retention_period

這個值會持續更新,且會在查詢時過時。如果您要使用這個值復原資料,請務必考量您查詢該值到啟動復原作業的當下時間。

point_in_time_recovery_enablement

PointInTimeRecoveryEnablement

是否啟用這個資料庫的時間點復原功能。

app_engine_integration_mode

AppEngineIntegrationMode

要用於這個資料庫的 App Engine 整合模式。

key_prefix

string

僅供輸出。這個資料庫的 key_prefix。這個 key_prefix 搭配專案 ID (「~」) 使用,可以建構從 Google App Engine 第一代執行階段中 Cloud Datastore API 傳回的應用程式 ID。

如果這個值空白,代表網址編碼金鑰的 appid 是 project_id (例如:foo,而非 v~foo)。

delete_protection_state

DeleteProtectionState

資料庫的防刪除功能狀態。

cmek_config

CmekConfig

選用設定。如有設定,代表這個資料庫已啟用 CMEK。

previous_id

string

僅供輸出。資料庫資源的舊資料庫 ID。只有已刪除的資料庫會填入這個欄位。

etag

string

伺服器會根據其他欄位的值計算這個總和檢查碼,也可能在更新和刪除要求時傳送,確保用戶端已取得最新的值再繼續。

AppEngineIntegrationMode

App Engine 整合模式類型。

列舉
APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED 未使用。
ENABLED 如果 App Engine 應用程式與這個資料庫位於相同區域,App Engine 設定就會影響這個資料庫。包括停用應用程式;以及並停用對資料庫的寫入功能
DISABLED

App Engine 不會影響這個資料庫處理要求的能力。

這是使用 Firestore API 建立的資料庫的預設設定。

CmekConfig

Firestore 資料庫的 CMEK (客戶自行管理的加密金鑰) 設定。如果沒有,表示資料庫受到預設的 Google 加密金鑰保護。

欄位
kms_key_name

string

執行個體類型,只有在與這個資料庫位於相同位置的金鑰才能用於加密。

如果是 Firestore 的 Nam5 多區域,這相當於 Cloud KMS 多區域。如果是 Firestore 的 eur3 多區域,這個欄位會對應至 Cloud KMS 多區域 (europe)。請參閱 https://cloud.google.com/kms/docs/locations

預期格式為 projects/{project_id}/locations/{kms_location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}

active_key_version[]

string

僅供輸出。目前使用的 KMS 金鑰版本。在金鑰輪替期間,可以有多個使用中的金鑰版本。

預期格式為 projects/{project_id}/locations/{kms_location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{key_version}

並行模式

交易的並行控制模式類型。

列舉
CONCURRENCY_MODE_UNSPECIFIED 未使用。
OPTIMISTIC 根據預設,請使用樂觀並行控制項。這個模式適用於 Cloud Firestore 資料庫。
PESSIMISTIC

根據預設,使用負面並行控制。這個模式適用於 Cloud Firestore 資料庫。

這是 Cloud Firestore 的預設設定。

OPTIMISTIC_WITH_ENTITY_GROUPS

根據預設,使用實體群組搭配樂觀並行控制。

這是 Cloud Datastore 唯一可用的模式。

此模式也適用於具備 Datastore 模式的 Cloud Firestore,但不建議使用。

DatabaseType

資料庫的類型。如要瞭解如何選擇,請參閱 https://cloud.google.com/datastore/docs/firestore-or-datastore

只有在資料庫中沒有任何內容時,才能變更模式。

列舉
DATABASE_TYPE_UNSPECIFIED 預設值。如果省略資料庫類型,則會使用這個值。
FIRESTORE_NATIVE Firestore 原生模式
DATASTORE_MODE 以及 Datastore 模式的 Firestore。

DeleteProtectionState

資料庫的防刪除功能狀態。

列舉
DELETE_PROTECTION_STATE_UNSPECIFIED 預設值。未指定刪除防護類型
DELETE_PROTECTION_DISABLED 防刪除功能已停用
DELETE_PROTECTION_ENABLED 防刪除功能已啟用

PointInTimeRecovery 啟用

啟用「時間點復原」功能。

列舉
POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED 未使用。
POINT_IN_TIME_RECOVERY_ENABLED

系統支援讀取過去 7 天內特定資料版本的資料:

  • 讀取過去 1 小時內的任何時間戳記
  • 依據 1 小時超過 1 小時的 7 天時間讀取超過 1 分鐘的快照

version_retention_periodearliest_version_time 可用來判斷支援的版本。

POINT_IN_TIME_RECOVERY_DISABLED 系統支援讀取過去 1 小時內任何版本的資料。

DeleteBackupRequest

FirestoreAdmin.DeleteBackup 的要求。

欄位
name

string

執行個體類型,要刪除的備份名稱。

格式為 projects/{project}/locations/{location}/backups/{backup}

刪除 BackupScheduleRequest

[FirestoreAdmin.DeleteBackupSchedules][] 的要求。

欄位
name

string

執行個體類型,備份排程的名稱,

格式化 projects/{project}/databases/{database}/backupSchedules/{backup_schedule}

刪除資料庫中繼資料

這個類型沒有任何欄位。

資料庫刪除作業的相關中繼資料。

刪除資料庫要求

FirestoreAdmin.DeleteDatabase 的要求。

欄位
name

string

執行個體類型,表單名稱 projects/{project_id}/databases/{database_id}

etag

string

資料庫目前的 Etag。如果提供的 etag 與資料庫目前的 etag 不符,將遭到封鎖,並傳回 FAILED_PRECONDITION 錯誤。

刪除索引要求

FirestoreAdmin.DeleteIndex 的要求。

欄位
name

string

執行個體類型,表單名稱 projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}

ExportDocumentsMetadata

FirestoreAdmin.ExportDocuments」中「google.longrunning.Operation」搜尋結果的中繼資料。

欄位
start_time

Timestamp

這項作業開始的時間。

end_time

Timestamp

此作業完成的時間。如果作業仍在進行中,則會未設定。

operation_state

OperationState

匯出作業的狀態。

progress_documents

Progress

這項作業的進度,以文件中。

progress_bytes

Progress

這項作業的進度 (以位元組為單位)。

collection_ids[]

string

要匯出的集合 ID。

output_uri_prefix

string

匯出文件的目標位置。

namespace_ids[]

string

要匯出的命名空間 ID。

snapshot_time

Timestamp

與匯出的資料庫版本相對應的時間戳記。如未指定,Google 無法保證匯出文件的一致性。

匯出文件要求

FirestoreAdmin.ExportDocuments 的要求。

欄位
name

string

執行個體類型,要匯出的資料庫。格式應該為:projects/{project_id}/databases/{database_id}

collection_ids[]

string

要匯出的集合 ID。未指定代表所有集合。這份清單中的每個產品素材資源集合 ID 都不得重複。

output_uri_prefix

string

輸出 URI。目前僅支援採用以下格式的 Google Cloud Storage URI:gs://BUCKET_NAME[/NAMESPACE_PATH],其中 BUCKET_NAME 是 Google Cloud Storage 值區的名稱,NAMESPACE_PATH 是選用的 Google Cloud Storage 命名空間路徑。選擇名稱時,請務必參考 Google Cloud Storage 命名規範:https://cloud.google.com/storage/docs/naming。如果 URI 是值區 (不含命名空間路徑),系統會根據開始時間產生前置字串。

namespace_ids[]

string

空白清單代表所有命名空間。對於不使用命名空間的資料庫,建議您採用這種方式。

空字串元素代表預設命名空間。如果資料庫有資料位於非預設命名空間,但不想納入資料,則應使用此選項。這份清單中的每個命名空間均不得重複。

snapshot_time

Timestamp

與要匯出的資料庫版本相對應的時間戳記。時間戳記必須是過去時間,四捨五入為分鐘,且早於 earliestVersionTime。如有指定,匯出的文件就會在指定時間呈現一致的資料庫檢視畫面。否則無法保證匯出文件的一致性。

ExportDocumentsResponse

透過 google.longrunning.Operation 回應欄位傳回。

欄位
output_uri_prefix

string

輸出檔案的位置。這項作業可在作業成功完成後,開始匯入 Cloud Firestore (這項專案或其他專案)。

欄位

代表資料庫中的單一欄位。

欄位會按照「集合群組」分組,代表資料庫中所有 ID 相同的集合。

欄位
name

string

執行個體類型,表單 projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_path} 的欄位名稱

欄位路徑可以是簡單的欄位名稱,例如address 或 map_value 中的欄位路徑,例如address.city 或特殊欄位路徑唯一有效的特殊欄位是 *,代表任何欄位。

欄位路徑可以使用 (backtick). The only character that needs to be escaped within a quoted field path is the backtick character itself, escaped using a backslash. Special characters in field paths that must be quoted include:*,., ``` (backtick),[,]` 和任何 ASCII 符號字元來引用。

例如:(注意:此處的註解是以 Markdown 語法編寫,因此使用另一層反引號來代表程式碼區塊) \address.city`represents a field namedaddress.city, not the map key cityin the fieldaddress. `*`represents a field named*`,不是任何欄位。

特殊的 Field 包含所有欄位的預設索引設定。這個欄位的資源名稱為:這個 Field 中定義的 projects/{project_id}/databases/{database_id}/collectionGroups/__default__/fields/* 索引,會套用至所有沒有 Field 索引設定的欄位。

index_config

IndexConfig

這個欄位的索引設定。如未設定,欄位索引功能會還原為 ancestor_field 定義的設定。如要明確移除這個欄位的所有索引,請指定內含空白索引清單的索引設定。

ttl_config

TtlConfig

這個 Field 的存留時間設定。如果您設定或取消設定,系統會針對含有這個 Field 的文件啟用或停用存留時間。

索引設定

這個欄位的索引設定。

欄位
indexes[]

Index

這個欄位支援的索引。

uses_ancestor_config

bool

僅供輸出。如果設為 true,Field 的索引設定是根據 ancestor_field 指定的設定進行設置。如果設為 False,系統會明確定義 Field 的索引設定。

ancestor_field

string

僅供輸出。指定 Field 的資源名稱,該資源名稱可供設定這個欄位的索引設定 (當 uses_ancestor_config 為 true 時);如果這個欄位沒有索引設定 (當 uses_ancestor_config 為 false 時),則設定這個欄位。

reverting

bool

僅在輸出為 true 時,Field 的索引設定正在還原中。完成後,索引設定會轉換至與 ancestor_field 指定欄位相同的狀態,此時 uses_ancestor_config 會是 truereverting 會是 false

Ttl 設定

針對設有這個 Field 的文件,其存留時間 (TTL) 設定。

如將時間戳記值儲存在已啟用 TTL 的欄位,系統將視為文件的絕對到期時間。過去的時間戳記值表示文件可立即到期。如果使用其他資料類型或欄位留空,則個別文件的到期日將會停用。

欄位
state

State

僅供輸出。存留時間設定的狀態。

狀態

所有文件套用存留時間設定的狀態。

列舉
STATE_UNSPECIFIED 未指定狀態或狀態不明。
CREATING 正在套用存留時間,有一個長時間執行的作業來追蹤變更。針對新撰寫的文件,系統會按照要求套用存留時間。針對現有文件要求的存留時間仍在處理中,所有現有文件的存留時間都處理完畢後,狀態就會變更為「有效」。
ACTIVE 所有文件的存留時間皆已啟用。
NEEDS_REPAIR 所有現有文件均無法啟用存留時間設定。新撰寫的文件會繼續套用存留時間。上次嘗試為這個Field啟用存留時間時,LRO 傳回失敗,可能會提供更多詳細資料。

FieldOperationMetadata

FirestoreAdmin.UpdateField」中「google.longrunning.Operation」搜尋結果的中繼資料。

欄位
start_time

Timestamp

這項作業開始的時間。

end_time

Timestamp

此作業完成的時間。如果作業仍在進行中,則會未設定。

field

string

這項作業所執行的欄位資源。例如:projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_path}

index_config_deltas[]

IndexConfigDelta

IndexConfigDelta 清單,說明這項作業的意圖。

state

OperationState

作業狀態。

progress_documents

Progress

這項作業的進度,以文件中。

progress_bytes

Progress

這項作業的進度 (以位元組為單位)。

ttl_config_delta

TtlConfigDelta

說明存留時間設定的差異。

IndexConfig Delta 值

索引設定變更的相關資訊。

欄位
change_type

ChangeType

指定索引的變更方式。

index

Index

正在變更的索引。

ChangeType

指定索引的變更方式。

列舉
CHANGE_TYPE_UNSPECIFIED 未指定或未知的變更類型。
ADD 正在新增單一欄位索引。
REMOVE 正在移除單一欄位索引。

TtlConfigDelta

存留時間設定變更的相關資訊。

欄位
change_type

ChangeType

指定存留時間設定的異動方式。

ChangeType

指定存留時間設定的變更方式。

列舉
CHANGE_TYPE_UNSPECIFIED 未指定或未知的變更類型。
ADD 正在新增存留時間設定,
REMOVE 正在移除存留時間設定,

GetBackupRequest

FirestoreAdmin.GetBackup 的要求。

欄位
name

string

執行個體類型,要擷取的備份名稱。

格式為 projects/{project}/locations/{location}/backups/{backup}

GetBackupScheduleRequest

FirestoreAdmin.GetBackupSchedule 的要求。

欄位
name

string

執行個體類型,備份排程的名稱,

格式化 projects/{project}/databases/{database}/backupSchedules/{backup_schedule}

GetDatabaseRequest

FirestoreAdmin.GetDatabase 的要求。

欄位
name

string

執行個體類型,表單名稱 projects/{project_id}/databases/{database_id}

取得取得欄位要求

FirestoreAdmin.GetField 的要求。

欄位
name

string

執行個體類型,表單名稱 projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_id}

取得索引要求

FirestoreAdmin.GetIndex 的要求。

欄位
name

string

執行個體類型,表單名稱 projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}

ImportDocumentsMetadata

FirestoreAdmin.ImportDocuments」中「google.longrunning.Operation」搜尋結果的中繼資料。

欄位
start_time

Timestamp

這項作業開始的時間。

end_time

Timestamp

此作業完成的時間。如果作業仍在進行中,則會未設定。

operation_state

OperationState

匯入作業的狀態。

progress_documents

Progress

這項作業的進度,以文件中。

progress_bytes

Progress

這項作業的進度 (以位元組為單位)。

collection_ids[]

string

要匯入的集合 ID。

input_uri_prefix

string

匯入文件的所在位置。

namespace_ids[]

string

要匯入的命名空間 ID。

匯入文件要求

FirestoreAdmin.ImportDocuments 的要求。

欄位
name

string

執行個體類型,要匯入的目標資料庫。格式應該為:projects/{project_id}/databases/{database_id}

collection_ids[]

string

要匯入的集合 ID。未指定表示匯入項目中包含的所有集合。

input_uri_prefix

string

匯出檔案的位置。這個值必須符合成功匯出的 ExportDocumentsResponse 的 output_uri_prefix。請參閱:google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix

namespace_ids[]

string

空白清單代表所有命名空間。對於不使用命名空間的資料庫,建議您採用這種方式。

空字串元素代表預設命名空間。如果資料庫有資料位於非預設命名空間,但不想納入資料,則應使用此選項。這份清單中的每個命名空間均不得重複。

索引

有了 Cloud Firestore 索引,您就能針對資料庫中的文件進行簡單複雜的查詢。

欄位
name

string

僅供輸出。這個索引的伺服器定義名稱。複合式索引的名稱格式為: projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{composite_index_id} 如果是單一欄位索引,此欄位將為空白。

query_scope

QueryScope

如果索引設有集合查詢範圍,則可在查詢時指定特定文件子項且集合 ID 相同的集合,對集合執行查詢。

如果索引指定了集合群組查詢範圍,則可在查詢時指定特定文件,且集合 ID 與這個索引相同的所有集合,對這類集合執行查詢。

api_scope

ApiScope

這個索引支援的 API 範圍。

fields[]

IndexField

此索引支援的欄位。

以複合式索引來說,最少需要 2 個欄位,最多 100 個欄位。最後一個欄位項目一律為欄位路徑 __name__。如果在建立時未指定 __name__ 為最後一個欄位,系統會自動新增該欄位,並將該欄位的方向與最後一個定義欄位相同。如果複合式索引的最後一個欄位並非方向性欄位,__name__ 就會排序 ASCENDING (除非已明確指定)。

如為單一欄位索引,這個值一律為一個項目,且欄位路徑會與關聯欄位的欄位路徑相同。

state

State

僅供輸出。索引的提供狀態。

API 範圍

API 範圍定義了查詢支援的 API (Firestore 原生或 Datastore 模式的 Firestore)。

列舉
ANY_API 該索引只能透過 Firestore Native Query API 使用。這是預設值。
DATASTORE_MODE_API 索引只能透過 Datastore Mode 查詢 API 使用。

索引欄位

索引中的欄位。欄位_path 說明已建立索引的欄位,value_mode 說明欄位值建立索引的方式。

欄位
field_path

string

可以是 name。如為單一欄位索引,這個值必須與欄位名稱相符,否則可能會遭到省略。

聯集欄位 value_mode。欄位值編入索引的方式。value_mode 只能採用下列其中一種設定:
order

Order

表示這個欄位支援按照指定的順序排序,或使用 =、!=、<、<=、>、>= 進行比較。

array_config

ArrayConfig

表示這個欄位支援對 array_value 作業。

vector_config

VectorConfig

表示這個欄位支援對向量最鄰近的鄰點和距離作業。

ArrayConfig

支援的陣列值設定。

列舉
ARRAY_CONFIG_UNSPECIFIED 這個索引不支援其他陣列查詢。
CONTAINS 這個索引支援陣列包含查詢。

順序

支援的排序。

列舉
ORDER_UNSPECIFIED 未指定順序。選項無效。
ASCENDING 欄位會依欄位值遞增排序。
DESCENDING 欄位值會依欄位值遞減排序。

VectorConfig

用於支援向量搜尋作業的索引設定

欄位
dimension

int32

執行個體類型,要套用這項設定的向量維度。

產生的索引只會包含這個維度的向量,並可用於具有相同維度的向量搜尋。

聯集欄位 type。使用的索引類型。type 只能採用下列其中一種設定:
flat

FlatIndex

表示向量索引是平面索引。

平面索引

這個類型沒有任何欄位。

這個索引可將向量儲存在平面資料結構中,並支援全面搜尋。

QueryScope

查詢範圍定義了查詢的執行範圍。這項資訊是透過 StructuredQuery 的 from 欄位指定。

列舉
QUERY_SCOPE_UNSPECIFIED 未指定查詢範圍。選項無效。
COLLECTION 如果索引已指定集合查詢範圍,則可在查詢時指定特定文件子項的集合,且該集合具有索引指定的集合 ID。
COLLECTION_GROUP 如為指定集合群組查詢範圍的索引,則可對具有索引指定集合 ID 的所有集合執行查詢。
COLLECTION_RECURSIVE 將集合的祖系加入索引。僅適用於 Datastore 模式資料庫。

狀態

索引的狀態。在建立索引期間,索引會處於 CREATING 狀態。如果索引建立成功,就會轉換為 READY 狀態。如果索引建立作業發生問題,索引會轉換為 NEEDS_REPAIR 狀態。

列舉
STATE_UNSPECIFIED 未指定狀態。
CREATING 正在建立索引。索引有一個執行中的長時間執行作業。寫入文件時,索引會更新。可能存在部分索引資料。
READY 索引已可供使用。寫入文件時,索引會更新。索引會完全填入套用該索引的所有已儲存文件。
NEEDS_REPAIR 正在建立索引,但發生錯誤。索引沒有執行中的長時間執行作業,且最近完成的長時間執行作業失敗。寫入文件時,索引不會更新。可能存在部分索引資料。請使用 google.longrunning.Operations API,判斷上次嘗試建立這個索引的作業失敗的原因,然後重新建立索引。

IndexOperationMetadata

FirestoreAdmin.CreateIndex」中「google.longrunning.Operation」搜尋結果的中繼資料。

欄位
start_time

Timestamp

這項作業開始的時間。

end_time

Timestamp

此作業完成的時間。如果作業仍在進行中,則會未設定。

index

string

執行這項作業的索引資源。例如:projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}

state

OperationState

作業狀態。

progress_documents

Progress

這項作業的進度,以文件中。

progress_bytes

Progress

這項作業的進度 (以位元組為單位)。

列出備份排程要求

FirestoreAdmin.ListBackupSchedules 的要求。

欄位
parent

string

執行個體類型,父項資料庫。

格式為 projects/{project}/databases/{database}

列出備份排程回應

FirestoreAdmin.ListBackupSchedules 的回應。

欄位
backup_schedules[]

BackupSchedule

所有備份排程的清單。

ListBackupsRequest

FirestoreAdmin.ListBackups 的要求。

欄位
parent

string

執行個體類型,要列出備份的來源位置。

格式為 projects/{project}/locations/{location}。使用 {location} = '-' 列出指定專案所有位置的備份。這樣就能列出單一位置或所有位置的備份。

ListBackupsResponse

FirestoreAdmin.ListBackups 的回應。

欄位
backups[]

Backup

專案的所有備份清單。

unreachable[]

string

無法擷取現有備份的位置清單。

當無法連上單一位置時,此回應會傳回部分結果集,並列出無法到達的位置清單,而不會使整個要求失敗。您可以針對單一位置重試要求,取得具體錯誤。

ListDatabasesRequest

要求列出專案所有位置中的 Firestore 資料庫。

欄位
parent

string

執行個體類型,表單 projects/{project_id} 的父項名稱

show_deleted

bool

如為 true,也會傳回已刪除的資源。

ListDatabasesResponse

專案的資料庫清單。

欄位
databases[]

Database

專案中的資料庫。

unreachable[]

string

如果無法列出個別資料庫的資料,就會記錄在這裡。

項目範例可能如下:projects/some_project/locations/some_location (如果資料庫所在的 Cloud 區域目前無法使用,在此情況下,我們無法擷取資料庫的所有詳細資料。若需傳送更詳細的錯誤訊息 (或擷取資源),請傳送「Get」或一份「List」要求特定位置的要求

列出欄位要求

FirestoreAdmin.ListFields 的要求。

欄位
parent

string

執行個體類型,表單 projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id} 的父項名稱

filter

string

要套用至清單結果的篩選器。目前,FirestoreAdmin.ListFields 僅支援已明確覆寫的資訊欄位。如要發出這項查詢,請使用包含 indexConfig.usesAncestorConfig:falsettlConfig:* 的篩選器呼叫 FirestoreAdmin.ListFields

page_size

int32

要傳回的結果數。

page_token

string

頁面權杖,從先前的 FirestoreAdmin.ListFields 呼叫傳回,可用於取得下一頁的結果。

列出欄位回應

FirestoreAdmin.ListFields 的回應。

欄位
fields[]

Field

要求的欄位。

next_page_token

string

網頁權杖,可用於要求其他結果頁面。如果空白,表示這是最後一頁。

列出索引要求

FirestoreAdmin.ListIndexes 的要求。

欄位
parent

string

執行個體類型,表單 projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id} 的父項名稱

filter

string

要套用至清單結果的篩選器。

page_size

int32

要傳回的結果數。

page_token

string

頁面權杖,從先前的 FirestoreAdmin.ListIndexes 呼叫傳回,可用於取得下一頁的結果。

列出索引回應

FirestoreAdmin.ListIndexes 的回應。

欄位
indexes[]

Index

要求的索引。

next_page_token

string

網頁權杖,可用於要求其他結果頁面。如果空白,表示這是最後一頁。

LocationMetadata

這個類型沒有任何欄位。

google.cloud.location.Location.metadata 的中繼資料訊息。

OperationState

說明作業的狀態。

列舉
OPERATION_STATE_UNSPECIFIED 未指定。
INITIALIZING 正在準備處理要求。
PROCESSING 正在處理要求。
CANCELLING 當使用者呼叫 google.longrunning.Operations.CancelOperation 後,要求正在取消。
FINALIZING 要求已處理完畢,並且正在進入最終階段。
SUCCESSFUL 已成功完成要求。
FAILED 要求已處理完畢,但發生錯誤。
CANCELLED 使用者呼叫 google.longrunning.Operations.CancelOperation 後,要求已取消。

進度

說明作業的進度。作業單位屬於一般性,必須根據使用 Progress 的位置解譯。

欄位
estimated_work

int64

預估工作量。

completed_work

int64

已完成的工作量。

RestoreDatabaseMetadata

從 [RestoreDatabase][google.firestore.admin.v1.RestoreDatabase] 要求指定的 long-running operation 中繼資料。

欄位
start_time

Timestamp

開始還原的時間。

end_time

Timestamp

還原作業完成的時間,為進行中的還原作業未設定。

operation_state

OperationState

還原作業的狀態。

database

string

要還原的資料庫名稱。

backup

string

備份還原作業的來源名稱。

progress_percentage

Progress

還原進度的預估剩餘時間百分比。

RestoreDatabaseRequest

[FirestoreAdmin.RestoreDatabase][google.firestore.admin.v1.RestoreDatabase] 的要求訊息。

欄位
parent

string

執行個體類型,要還原資料庫的專案。格式為 projects/{project_id}

database_id

string

執行個體類型,用於資料庫的 ID,會成為資料庫資源名稱的最終元件。這個資料庫 ID 不得與現有資料庫建立關聯。

此值長度應介於 4 至 63 個字元之間。有效的字元為 /[a-z][0-9]-/,開頭必須為英文字母,最後一個字母或數字。不得與 UUID 類似 /[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}/。

「(預設)」資料庫 ID 也有效。

聯集欄位 source

source 只能採用下列其中一種設定:

backup

string

用來還原的備份資料。必須來自與父項相同的專案。

格式為:projects/{project_id}/locations/{location}/backups/{backup}

更新備份排程要求

FirestoreAdmin.UpdateBackupSchedule 的要求。

欄位
backup_schedule

BackupSchedule

執行個體類型,要更新的備份排程。

update_mask

FieldMask

要更新的欄位清單。

更新資料庫中繼資料

這個類型沒有任何欄位。

更新資料庫作業的相關中繼資料。

更新資料庫要求

FirestoreAdmin.UpdateDatabase 的要求。

欄位
database

Database

執行個體類型,要更新的資料庫。

update_mask

FieldMask

要更新的欄位清單。

更新欄位要求

FirestoreAdmin.UpdateField 的要求。

欄位
field

Field

執行個體類型,要更新的欄位。

update_mask

FieldMask

相對於欄位的遮罩。如果指定此選項,則只有這個欄位_mask 指定的設定會更新於欄位中。

每週重複

代表在一週中特定日期執行的週期性排程。

時區為世界標準時間 (UTC)。

欄位
day

DayOfWeek

要在星期幾執行。

不允許使用 DAY_OF_WEEK_UNSPECIFIED。