Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

建立及更新資料結構定義

在資料擷取部署的應用程式中，已連結的 Vision Warehouse (corpus) 包含一或多個媒體物件 assets。您可以透過 dataSchema 和使用者提供的 annotation 資源，提供這些媒體物件 assets 的詳細資料。

您必須先建立資料結構定義資源，才能建立具有該資料結構定義鍵的 annotation 資源。建立資料架構 (dataSchema 資源) 後，Gemini Enterprise Agent Platform Vision API 就能解讀媒體註解，接著您就可以在資料倉儲中建立媒體的 annotation 資源。

建立資料結構定義 (API)

REST

使用任何要求資料之前，請先修改下列項目的值：

REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解地區化端點。
PROJECT_NUMBER：您的 Google Cloud 專案編號。
LOCATION_ID：您使用 Agent Platform Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
CORPUS_ID：目標語料庫的 ID。
DATASCHEMA_KEY：這個鍵必須與使用者指定的註解鍵相符，且在 corpus 內不得重複。例如：data-key。
ANNOTATION_DATA_TYPE：註解的資料類型。可用的值包括：
- DATA_TYPE_UNSPECIFIED
- INTEGER
- FLOAT
- STRING
- DATETIME
- GEO_COORDINATE
- PROTO_ANY
- BOOLEAN
詳情請參閱 API 參考說明文件。
ANNOTATION_GRANULARITY：這個 dataSchema 下註解的精細程度。可用的值包括：
- GRANULARITY_UNSPECIFIED - 未指定精細程度。
- GRANULARITY_ASSET_LEVEL - 素材資源層級的精細程度 (註解不得包含媒體素材資源的時間分區資訊)。
- GRANULARITY_PARTITION_LEVEL - 分區層級的精細程度 (註解必須包含媒體資產的時間分區資訊)。
SEARCH_STRATEGY：其中一個可用的列舉值。要套用至註解鍵的搜尋策略類型。可用的值包括：
- NO_SEARCH
- EXACT_SEARCH
- SMART_SEARCH

HTTP 方法和網址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas

JSON 要求內文：

{
  "key": "DATASCHEMA_KEY",
  "schema_details": {
    "type": "ANNOTATION_DATA_TYPE",
    "granularity": "ANNOTATION_GRANULARITY",
    "search_strategy": {
      "search_strategy_type": "SEARCH_STRATEGY"
    }
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "data-key",
  "schemaDetails": {
    "type": "BOOLEAN",
    "granularity": "GRANULARITY_ASSET_LEVEL",
    "searchStrategy": {
      "search_strategy_type": "EXACT_SEARCH"
    }
  }
}

更新資料結構定義 (API)

REST 和指令列

下列程式碼使用 projects.locations.corpora.dataSchemas.patch 方法更新 dataSchema。

這個範例會在要求網址中使用 ?updateMask=schemaDetails.type,schemaDetails.granularity，並在要求主體中加入新的 schemaDetails.type 和 schemaDetails.granularity 值，以更新資料結構。

使用任何要求資料之前，請先修改下列項目的值：

REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解地區化端點。
PROJECT_NUMBER：您的 Google Cloud 專案編號。
LOCATION_ID：您使用 Agent Platform Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
CORPUS_ID：目標語料庫的 ID。
DATASCHEMA_ID：目標資料結構定義的 ID。
?updateMask=fieldToUpdate：可套用 updateMask 的可用欄位之一。在要求主體中指定對應的新欄位值。這個新值會取代現有的欄位值。可用欄位：
- 鍵：?updateMask=key
- 結構定義類型：?updateMask=schemaDetails.type
- 結構定義精細程度：?updateMask=schemaDetails.granularity
- 結構定義搜尋策略類型：?updateMask=schemaDetails.searchStrategy.searchStrategyType
- 更新所有欄位：?updateMask=*

HTTP 方法和網址：

PATCH https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity

JSON 要求內文：

{
  "key": "original-data-key",
  "schemaDetails": {
    "type":"INTEGER",
    "granularity":"GRANULARITY_PARTITION_LEVEL"
    "searchStrategy": {
      "searchStrategyType": "NO_SEARCH"
    }
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "original-data-key",
  "schemaDetails": {
    "type": "INTEGER",
    "granularity": "GRANULARITY_PARTITION_LEVEL",
    "searchStrategy": {
      "searchStrategyType": "NO_SEARCH"
    }
  }
}

新增自訂結構體資料結構

自訂結構體可讓使用者定義更複雜的容器來保存值，並提供搜尋功能。如要使用這項功能，必須定義資料結構，例如：

REST

使用任何要求資料之前，請先修改下列項目的值：

REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解地區化端點。
PROJECT_NUMBER：您的 Google Cloud 專案編號。
LOCATION_ID：您使用 Agent Platform Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas

JSON 要求內文：

{
  "key": "person",
  "schema_details" : {
    "type":"CUSTOMIZED_STRUCT",
    "granularity":"GRANULARITY_ASSET_LEVEL",
    "customized_struct_config": {
      "field_schemas": {
         "name": {
            "type":"STRING",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         },
         "age": {
            "type":"FLOAT",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         }
      }
    }
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "person",
  "schemaDetails" : {
    "type":"CUSTOMIZED_STRUCT",
    "granularity":"GRANULARITY_ASSET_LEVEL",
    "customized_struct_config": {
      "field_schemas": {
         "name": {
            "type":"STRING",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         },
         "age": {
            "type":"FLOAT",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         }
      }
    }
  }
}

之後即可插入註解

使用任何要求資料之前，請先修改下列項目的值：

REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解地區化端點。
PROJECT_NUMBER：您的 Google Cloud 專案編號。
LOCATION_ID：您使用 Agent Platform Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
CORPUS_ID：目標語料庫的 ID。
ASSET_ID：目標資產的 ID。

HTTP 方法和網址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations

JSON 要求內文：

{
  "user_specified_annotation" : {
    "key": "person",
    "value": {
      "customized_struct_value":{
        "elements" : {
          "name": {
            "str_value":"John"
          },
          "age": {
            "float_value":10.5
          }
        }
      }
    }
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID",
  "userSpecifiedAnnotation": {
    "key": "person",
    "value": {
      "customized_struct_value":{
        "elements" : {
          "name": {
            "str_value":"John"
          },
          "age": {
            "float_value":10.5
          }
        }
      }
    }
  }
}

註解建立索引後，即可發出搜尋要求，如下所示：

使用任何要求資料之前，請先修改下列項目的值：

REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解地區化端點。
PROJECT_NUMBER：您的 Google Cloud 專案編號。
LOCATION_ID：您使用 Agent Platform Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID:searchAssets

JSON 要求內文：

{
  "page_size": 10,
  "criteria": {
    "field": "person.name",
    "text_array": {
      "txt_values": "John"
    },
  },
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID:searchAssets"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID:searchAssets" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

回應

{
  "searchResultItems": [
    {
      "asset": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID1",
      "segments": [
        {
          "startTime": "2020-09-01T02:51:55Z",
          "endTime": "2020-09-01T02:52:09.996016Z"
        }
      ],
      "segment": {
        "startTime": "2023-07-07T16:36:10.652575Z",
        "endTime": "2023-07-07T20:30:48.812575Z"
      }
    }
  ]
}

修改倉儲結構定義詳細資料 (主控台)

系統會透過應用程式從模型生成結構定義欄位。您也可以新增自訂欄位。

修改可切面欄位後，您就能使用這些欄位搜尋倉庫。

控制台

開啟 Gemini Enterprise Agent Platform Vision 資訊主頁的「倉庫」分頁。

前往「倉庫」分頁
找出所需倉庫，然後選取倉庫名稱。「倉庫詳細資料」頁面隨即顯示。
選取要啟用搜尋功能的欄位。

在使用者介面中選取可切面的搜尋欄位

建立及更新資料結構定義 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立資料結構定義 (API)

REST

curl

PowerShell

更新資料結構定義 (API)

REST 和指令列

curl

PowerShell

新增自訂結構體資料結構

REST

curl

PowerShell

curl

PowerShell

curl

PowerShell

回應

修改倉儲結構定義詳細資料 (主控台)

控制台

建立及更新資料結構定義