更新結構定義

您可以為任何包含支援結構描述的資料的資料更新結構描述,例如結構化資料含有結構化資料的網站資料,或其他含有中繼資料的非結構化資料

您可以在 Google Cloud 控制台中更新結構定義,也可以使用 schemas.patch API 方法。只有透過 REST API 才能更新網站的結構定義。

如要更新結構定義,您可以新增欄位、變更欄位的可建立索引、可搜尋和可擷取的註解,或是將欄位標示為主要屬性,例如 titleuridescription

更新結構定義

您可以在 Google Cloud 控制台或使用 API 更新結構定義。

控制台

如要在 Google Cloud 主控台中更新結構定義,請按照下列步驟操作:

  1. 請參閱「規定和限制」一節,確認結構定義更新是否有效。

  2. 如果您要更新欄位註解 (將欄位設為可索引、可擷取、可動態面向、可搜尋或可完成),請參閱「設定欄位設定」,瞭解各註解類型的限制和要求。

  3. 確認您已完成資料匯入作業。否則結構定義可能尚未可供編輯。

  4. 前往 Google Cloud 控制台的「AI Applications」頁面。

    AI 應用程式

  5. 在導覽選單中,按一下「資料儲存庫」

  6. 在「Name」欄中,按一下含有您要更新的架構的資料儲存庫。

  7. 按一下「Schema」分頁標籤,查看資料的結構定義。

    如果這是您第一次編輯欄位,這個分頁可能會是空白。

  8. 按一下 [Edit] (編輯) 按鈕。

  9. 更新結構定義:

    • 對應主要屬性:在結構定義的「主要屬性」欄中,選取要對應欄位的關鍵屬性。舉例來說,如果名為 details 的欄位一律包含文件的說明,請將該欄位對應至鍵屬性 Description

    • 更新維度數量 (進階):如果您在 Vertex AI Search 中使用自訂向量嵌入,可以更新這個設定。請參閱「進階:使用自訂嵌入資料」。

    • 更新欄位註解:如要更新欄位的註解,請選取或取消選取欄位的註解設定。可用的註解包括「可擷取」、「可建立索引」、「可使用動態商情項目」、「可供搜尋」和「可完成」。部分欄位設定有限制。如要瞭解各註解類型的說明和規定,請參閱「設定欄位設定」。

    • 新增欄位:在匯入含有這些欄位的文件之前,先在結構定義中新增欄位,這樣 AI 應用程式在匯入後重新為資料建立索引時,所需時間就會縮短。

      1. 按一下「新增欄位」展開該部分。

      2. 按一下 add_box「新增節點」,然後指定新欄位的設定。

        如要指示陣列,請將「陣列」設為「是」。舉例來說,如要新增字串陣列,請將「type」設為 string,並將「Array」設為 Yes

        對於網站資料儲存庫索引,預設情況下,您新增的所有欄位都是陣列。

  10. 按一下「儲存」套用結構定義變更。

    變更結構定義會觸發重新建立索引的動作。以大型資料儲存庫來說,重新建立索引的作業可能需要數小時才能完成。

REST

如要使用 API 更新結構定義,請按照下列步驟操作:

  1. 請參閱「限制和限制」和「限制範例 (僅限 REST)」部分,確認結構定義變更是否有效。

    如要更新資料儲存庫的結構定義,以便使用含有中繼資料的網站或非結構化資料,請跳至步驟 5 呼叫 schema.patch 方法。

  2. 如果您要更新欄位註解 (將欄位設為可索引、可擷取、可動態面向或可搜尋),請參閱「設定欄位設定」,瞭解各註解類型的限制和要求。

  3. 如果您要編輯自動偵測的結構定義,請務必完成資料攝入作業。否則,系統可能尚未開放編輯結構定義。

  4. 找出資料儲存庫 ID。如果您已取得資料儲存庫 ID,請略過至下一個步驟。

    1. 前往 Google Cloud 控制台的「AI Applications」頁面,然後在導覽選單中按一下「資料儲存庫」

      前往「資料儲存庫」頁面

    2. 點按資料儲存庫的名稱。

    3. 在資料儲存庫的「資料」頁面中,取得資料儲存庫 ID。

  5. 使用 schemas.patch API 方法,以 JSON 物件形式提供新的 JSON 結構定義。

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
    -d '{
      "structSchema": JSON_SCHEMA_OBJECT
    }'
    

    更改下列內容:

    • PROJECT_ID: Google Cloud 專案的 ID。
    • DATA_STORE_ID:Vertex AI Search 資料儲存庫的 ID。
    • JSON_SCHEMA_OBJECT:新的 JSON 結構定義做為 JSON 物件。例如:

      {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "keyPropertyMapping": "title"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "keyPropertyMapping": "category"
            }
          },
          "uri": {
            "type": "string",
            "keyPropertyMapping": "uri"
          }
        }
      }
  6. 選用步驟:按照「查看結構定義」中的程序查看結構定義。

C#

詳情請參閱 AI Applications C# API 參考說明文件

如要向 AI Applications 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;

public sealed partial class GeneratedSchemaServiceClientSnippets
{
    /// <summary>Snippet for UpdateSchema</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void UpdateSchemaRequestObject()
    {
        // Create client
        SchemaServiceClient schemaServiceClient = SchemaServiceClient.Create();
        // Initialize request argument(s)
        UpdateSchemaRequest request = new UpdateSchemaRequest
        {
            Schema = new Schema(),
            AllowMissing = false,
        };
        // Make the request
        Operation<Schema, UpdateSchemaMetadata> response = schemaServiceClient.UpdateSchema(request);

        // Poll until the returned long-running operation is complete
        Operation<Schema, UpdateSchemaMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Schema result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Schema, UpdateSchemaMetadata> retrievedResponse = schemaServiceClient.PollOnceUpdateSchema(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Schema retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

詳情請參閱 AI Applications Go API 參考說明文件

如要向 AI Applications 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewSchemaClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.UpdateSchemaRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#UpdateSchemaRequest.
	}
	op, err := c.UpdateSchema(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳情請參閱 AI Applications Java API 參考說明文件

如要向 AI Applications 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import com.google.cloud.discoveryengine.v1.Schema;
import com.google.cloud.discoveryengine.v1.SchemaServiceClient;
import com.google.cloud.discoveryengine.v1.UpdateSchemaRequest;

public class SyncUpdateSchema {

  public static void main(String[] args) throws Exception {
    syncUpdateSchema();
  }

  public static void syncUpdateSchema() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
      UpdateSchemaRequest request =
          UpdateSchemaRequest.newBuilder()
              .setSchema(Schema.newBuilder().build())
              .setAllowMissing(true)
              .build();
      Schema response = schemaServiceClient.updateSchemaAsync(request).get();
    }
  }
}

Python

詳情請參閱 AI Applications Python API 參考說明文件

如要向 AI Applications 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_update_schema():
    # Create a client
    client = discoveryengine_v1.SchemaServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.UpdateSchemaRequest(
    )

    # Make the request
    operation = client.update_schema(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

詳情請參閱 AI Applications Ruby API 參考說明文件

如要向 AI Applications 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

require "google/cloud/discovery_engine/v1"

##
# Snippet for the update_schema call in the SchemaService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::SchemaService::Client#update_schema.
#
def update_schema
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::SchemaService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::UpdateSchemaRequest.new

  # Call the update_schema method.
  result = client.update_schema request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

需求條件和限制

更新結構定義時,請確認新結構定義與要更新的結構定義相容。如要使用不回溯相容的新結構定義更新結構定義,您必須刪除資料儲存庫中的所有文件、刪除結構定義,然後建立新的結構定義。

更新結構定義會觸發所有文件的重新建立索引作業。這可能需要花費時間,且會產生額外費用:

  • Time. 重新建立大型資料儲存庫的索引可能需要數小時或數天。

  • 支出。重新建立索引可能會產生費用,具體取決於剖析器。舉例來說,使用 OCR 剖析器或版面配置剖析器重新建立索引的資料儲存空間都會產生費用。詳情請參閱 Document AI 功能價格

結構定義更新不支援下列項目:

  • 變更欄位類型結構定義更新不支援變更欄位類型。舉例來說,已對應至整數的欄位無法變更為字串。
  • 移除欄位。一旦定義欄位,就無法移除。您可以繼續新增欄位,但無法移除現有欄位。

限制範例 (僅限 REST)

本節將列舉有效和無效的結構定義更新類型範例。這些範例使用以下 JSON 結構定義範例:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    }
  }
}

支援的更新範例

系統支援下列範例結構定義的更新。

  • 新增欄位。在這個範例中,properties.uri 欄位已新增至結構定義。

    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "keyPropertyMapping": "description"
        },
        "uri": { // Added field. This is supported.
          "type": "string",
          "keyPropertyMapping": "uri"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string",
            "keyPropertyMapping": "category"
          }
        }
      }
    }
    
  • titledescriptionuri 新增或移除關鍵屬性註解。在這個範例中,keyPropertyMapping 已新增至 title 欄位。

    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "keyPropertyMapping": "title" // Added "keyPropertyMapping". This is supported.
        },
        "description": {
          "type": "string",
          "keyPropertyMapping": "description"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string",
            "keyPropertyMapping": "category"
          }
        }
      }
    }
    

無效的結構定義更新示例

系統不支援下列結構定義範例的更新。

  • 變更欄位類型在這個範例中,title 欄位的類型已從字串變更為數字。系統不支援這項功能。

      {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "title": {
            "type": "number" // Changed from string. Not allowed.
          },
          "description": {
            "type": "string",
            "keyPropertyMapping": "description"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "keyPropertyMapping": "category"
            }
          }
        }
      }
    
  • 移除欄位。在這個範例中,已移除 title 欄位。系統不支援這項功能。

      {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          // "title" is removed. Not allowed.
          "description": {
            "type": "string",
            "keyPropertyMapping": "description"
          },
          "uri": {
            "type": "string",
            "keyPropertyMapping": "uri"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "keyPropertyMapping": "category"
            }
          }
        }
      }
    

後續步驟