Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建立及管理參數化檢視區塊

您可以在 Bigtable 中從邏輯檢視區塊建立參數化檢視區塊，然後對參數化檢視區塊執行作業。

閱讀本頁面之前，請先熟悉「參數化檢視區塊總覽」。

事前準備

如果您打算使用 Google Cloud CLI，請按照下列步驟操作：

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。
若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
執行下列指令，初始化 gcloud CLI：
```
gcloud init
```
注意：您可以直接在 Google Cloud 控制台執行 gcloud CLI，不用安裝 Google Cloud CLI。如要在 Google Cloud 控制台執行 gcloud CLI，請使用 Cloud Shell。

必要的角色

如要取得建立及管理參數化檢視區塊所需的權限，請要求管理員授予您執行個體的 Bigtable 管理員 (roles/bigtable.admin) 角色。

或者，您可以在執行個體層級要求下列權限：

建立：bigtable.logicalViews.create
更新狀態：bigtable.logicalViews.update
刪除：bigtable.logicalViews.delete
清單：bigtable.logicalViews.list

如要建立參數化檢視區塊，您也必須至少具備來源資料表的 bigtable.tables.readRows 權限。

建立參數化檢視區塊

參數化檢視表是由 SQL SELECT 陳述式定義的虛擬資料表，可包含 VIEW_PARAMETERS() 函式。

控制台

在 Google Cloud 控制台中，開啟 Bigtable 執行個體清單。

開啟執行個體清單
從清單中選取執行個體。
在導覽窗格中，按一下「Bigtable Studio」。
按一下「新分頁」選單開啟新分頁，然後選取「編輯器」。
在查詢編輯器中編寫 SQL 查詢。查詢定義必須呼叫 VIEW_PARAMETERS() 函式，才能指定一或多個檢視區塊參數。例如：
```
SELECT *
FROM TABLE_ID
WHERE STARTS_WITH(_key, CAST(VIEW_PARAMETERS('PARAM_NAME') AS BYTES))
```
更改下列內容：
- TABLE_ID：來源資料表的 ID。
- PARAM_NAME：檢視區塊參數的名稱 (以單引號括住)，會做為 VIEW_PARAMETERS() 函式的引數傳遞。這會定義參數名稱，而非執行階段值。查詢參數化檢視區塊時，您會提供執行階段值。
如果查詢是有效的 SQL，系統會顯示「有效」訊息。
選用：如要以 SQL 樣式設定陳述式格式，請按一下「格式」。
按一下「儲存」，然後選取「儲存為邏輯 view」。
在「儲存邏輯檢視區塊」對話方塊中，輸入檢視區塊名稱，然後按一下「儲存」。

檢視畫面會顯示在「Explorer」窗格的「Logical Views」清單中，並附有「variable_add」variable_add參數化檢視畫面圖示。

如要進一步瞭解如何使用查詢編輯器，請參閱「使用 Bigtable Studio 管理資料」。

gcloud

如要建立參數化檢視區塊，請使用 gcloud bigtable logical-views create 指令。

gcloud bigtable logical-views create VIEW \
  --instance=INSTANCE \
  --query="SELECT * FROM TABLE_ID WHERE STARTS_WITH(_key, CAST(VIEW_PARAMETERS('PARAM_NAME') AS BYTES))"

更改下列內容：

VIEW：新參數化檢視區塊的 ID，最多 128 個字元。這個 ID 在執行個體中的所有表格 ID 和檢視區塊 ID 中不得重複。
INSTANCE：要在其中建立參數化檢視區塊的執行個體 ID。
TABLE_ID：來源資料表的 ID。
PARAM_NAME：檢視區塊參數的名稱 (以單引號括住)，會做為 VIEW_PARAMETERS() 函式的引數傳遞。這會定義參數名稱，而非執行階段值。查詢參數化檢視區塊時，您會提供執行階段值。

選用：

如要防止系統刪除參數化檢視區塊，請在指令中附加 --deletion-protection 標記。如未套用這項設定，檢視畫面可能會遭到刪除。您也可以附加 --no-deletion-protection，明確允許刪除檢視區塊。詳情請參閱本文的「更新參數化檢視區塊」一節。

使用結構化資料列索引鍵建立參數化檢視畫面

如果資料表使用結構化資料列索引鍵，則可依資料列索引鍵的特定區隔進行篩選。詳情請參閱「管理資料列索引鍵結構定義」。

舉例來說，如果購買記錄資料表中的資料列索引鍵儲存了使用者、購買日期的時間戳記和訂單 ID，並以 # 符號做為分隔符號，您可以指定資料列結構定義如下：

field {
    field_name: "user_id"
    type: { bytesType { encoding { raw {} } } }
  }
  field {
    field_name: "reversed_timestamp"
    type: { timestampType { encoding { unixMicrosInt64 { encoding: {           orderedCodeBytes: {} } } } } }
  }
  field {
    field_name: "order_id"
    type: { stringType { encoding { utf8Bytes {} } } }
  }
  encoding {
    delimitedBytes { delimiter "#" }
  }

接著，您可以建立資料檢視，並根據 User-ID 欄位進行篩選：

控制台

在 Bigtable Studio 中開啟查詢編輯器，然後輸入 SQL 查詢，依據資料列索引鍵區隔進行篩選：
```
SELECT *
FROM TABLE_ID
WHERE user_id = CAST(VIEW_PARAMETERS('user_id') AS BYTES)
```
將 TABLE_ID 替換為來源資料表的 ID。
按一下「儲存」，然後選取「儲存為邏輯 view」。
在「儲存邏輯檢視區塊」對話方塊中，輸入檢視區塊名稱，然後按一下「儲存」。

檢視畫面會顯示在「Explorer」窗格的「Logical Views」清單中，並附有「variable_add」variable_add參數化檢視畫面圖示。

gcloud

如要使用結構化資料列索引鍵建立參數化檢視區塊，請使用 gcloud bigtable logical-views create 指令。

gcloud bigtable logical-views create VIEW \
    --instance=INSTANCE \
    --query="SELECT * FROM TABLE_ID WHERE user_id = CAST(VIEW_PARAMETERS('user_id') AS BYTES)"

更改下列內容：

VIEW：新參數化檢視區塊的 ID，最多 128 個字元。ID 在執行個體中的資料表 ID 和檢視區塊 ID 中不得重複。
INSTANCE：要在其中建立參數化檢視區塊的執行個體 ID。
TABLE_ID：來源資料表的 ID。

更新參數化檢視

更新參數化檢視區塊的方式與更新邏輯檢視區塊相同。

刪除參數化檢視畫面

刪除參數化檢視區塊的方式與刪除邏輯檢視區塊相同。

查看參數化檢視區塊的相關資訊

您會以查看執行個體邏輯檢視區塊清單的方式，查看參數化檢視區塊清單。

控制台

在 Google Cloud 控制台中，開啟 Bigtable 執行個體清單。

開啟執行個體清單
從清單中選取執行個體。
在導覽窗格中，按一下「Bigtable Studio」。
在「Explorer」窗格中，展開「Logical Views」。

參數化檢視畫面會顯示在清單中，並附有 variable_add 參數化檢視畫面圖示，與標準邏輯檢視畫面有所區別。
如果執行個體有超過 10 個檢視畫面，請按一下「顯示更多」載入下 10 個。

gcloud

如要查看執行個體的邏輯檢視區塊清單，請使用 gcloud bigtable logical-views list 指令。

gcloud bigtable logical-views list --instance=INSTANCE

將 INSTANCE 替換為執行個體 ID。

查詢參數化檢視區塊

查詢參數化檢視表的方式與一般資料表類似，但您會在要求中提供 view_parameters 對應。

控制台

在 Google Cloud 控制台中，開啟 Bigtable 執行個體清單。

開啟執行個體清單
從清單中選取執行個體。
在導覽窗格中，按一下「Bigtable Studio」。
在「Explorer」窗格中，展開「Logical Views」。
在要查詢的參數化檢視畫面旁，依序點選 more_vert「View actions」(查看動作) 選單和「Query view」(查詢檢視畫面)。

系統會開啟「參數」窗格，並預先填入檢視區塊參數名稱。
在「查看參數」中，於「值」欄位中輸入每個必要參數的執行階段值。

參數值會以字串形式傳遞。如果檢視定義中的參數轉換為其他類型 (例如整數或位元組)，請輸入原始字串值。
選用：如要新增更多參數，請按一下「新增參數」，然後輸入參數名稱和值。檢視區塊參數中的參數名稱不得重複。
按一下 [儲存]。
在查詢編輯器中，按一下「執行」。

查詢結果會顯示在「結果」表格中。

如果執行查詢時未提供必要檢視參數，結果部分會顯示錯誤訊息和「編輯參數」按鈕。按一下「編輯參數」，開啟「參數」窗格，然後輸入缺少的參數值。

系統會為每個查詢編輯器分頁設定參數值。如果在工作階段期間離開 Bigtable Studio，然後返回，系統會保留開啟的分頁、查詢、結果和設定的參數。

Java

以下範例說明如何查詢名為 purchase_history_pv 的參數化檢視區塊，該檢視區塊會根據使用者 ID 篩選資料：

// Assumes 'purchase_history_pv' was created with the definition:
// SELECT * FROM purchases WHERE user_id = CAST(VIEW_PARAMETERS('user_id') AS BYTES)

String query = "SELECT customer_info[email], order_details[status], order_info[items] from purchase_history_pv";
PreparedStatement preparedStatement = dataClient.prepareStatement(query);
BoundStatement boundStatement = preparedStatement.bind().build();

// The user ID is now passed out-of-band in a view parameters map.
Map<String, Value> viewParameters = new HashMap<>();
viewParameters.put("user_id", Value.newBuilder().setType(stringType()).setStringValue(userId).build());

// Execute the query, passing the view parameters using a proto field in the request.
ResultSet rs = dataClient.executeQuery(
    boundStatement,
    viewParameters
);

這樣一來，使用者就無法查看或操控查詢中的 user_id 參數，提供乾淨的邏輯分隔。

後續步驟

在代理程式應用程式中使用參數化檢視畫面