更新結構定義

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

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

如要更新結構定義，請新增欄位、變更欄位的可建立索引、可搜尋和可擷取註解，或是將欄位標示為主要屬性，例如 title、uri 和 description。

重要事項： Google 強烈建議您更新結構化資料，加入重要屬性對應，尤其是 title。確保結果正確顯示，並協助 AI 應用程式找出重要資訊，進而生成更優質的結果。

更新結構定義

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

注意： 編輯結構定義會重新為資料儲存庫建立索引。 如果資料儲存庫較大，建立索引的作業可能需要數小時才能完成。

控制台

如要在 Google Cloud 控制台中更新結構定義，請按照下列步驟操作：

1. 請參閱「需求條件和限制」一節，確認結構定義更新是否有效。

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

3. 確認您已完成資料匯入。否則可能還無法編輯結構定義。

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

   AI 應用程式

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

6. 在「名稱」欄中，按一下要更新架構的資料儲存庫。

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

   如果您是第一次編輯欄位，這個分頁可能不會顯示任何內容。

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

9. 更新結構定義：

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

   • 更新維度數量 (進階)：如果您使用 Vertex AI Search 的自訂向量嵌入，可以更新這項設定。請參閱「進階：使用自訂嵌入」。

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

   • 新增欄位：在匯入含有這些欄位的新文件前，先在結構定義中新增欄位，可縮短 AI 應用程式在匯入後重新編製資料索引的時間。

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

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

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

        如果是網站資料儲存庫索引，您新增的所有欄位預設都是陣列。

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

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

REST

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

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

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

2. 如要更新欄位註解 (將欄位設為可建立索引、可擷取、動態可切面或可搜尋)，請參閱「設定欄位設定」一文，瞭解各註解類型的限制和規定。

3. 如果您要編輯自動偵測到的結構定義，請務必先完成資料擷取作業。否則，您可能還無法編輯結構定義。

4. 找出資料儲存庫 ID。如果已有資料商店 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面，然後在導覽選單中點選「Data Stores」。

      前往「資料儲存庫」頁面

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

     指令和結果範例

     curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
     "structSchema": {
     "$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"
     }
     }
     }
     }'
     
     {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
     "metadata": {
     "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
     }
     }
     

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

需求條件和限制

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

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

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

• 費用。視剖析器而定，重新建立索引可能會產生費用。舉例來說，如果使用 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"
        }
      }
    }
  }
  

• 為 title、description 或 uri 新增或移除重要屬性註解。在這個範例中，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"
          }
        }
      }
    }
  

後續步驟

• 查看結構化資料的結構定義
• 刪除結構化資料的結構定義
• 預覽搜尋結果