管理資料結構定義

您可以使用 Vision Warehouse API,透過指令列管理 Vision Warehouse 資源。

建立資料結構定義

圖片語料庫只能建立素材資源層級的細微資料結構定義。串流影片語料庫可建立素材資源層級的精細資料結構定義,以及分區層級的精細資料結構定義。批次影片語料庫可建立素材資源層級精細程度的資料結構定義,以及分割區層級精細程度的資料結構定義。

REST

使用任何要求資料之前,請先替換以下項目:

  • REGIONALIZED_ENDPOINT:端點可能包含與 LOCATION_ID 相符的前置字串,例如 europe-west4-。進一步瞭解 地區化端點
  • PROJECT_NUMBER:您的 Google Cloud專案編號
  • LOCATION_ID:您使用 Vertex AI Vision 的區域。例如:us-central1europe-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

將要求主體儲存在名為 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

將要求主體儲存在名為 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"
    }
  }
}

新增自訂結構體資料結構定義

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

REST

使用任何要求資料之前,請先替換以下項目:

  • REGIONALIZED_ENDPOINT:端點可能包含與 LOCATION_ID 相符的前置字串,例如 europe-west4-。進一步瞭解 地區化端點
  • PROJECT_NUMBER:您的 Google Cloud專案編號
  • LOCATION_ID:您使用 Vertex AI Vision 的區域。例如:us-central1europe-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

將要求主體儲存在名為 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:您使用 Vertex AI Vision 的區域。例如:us-central1europe-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

將要求主體儲存在名為 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:您使用 Vertex AI Vision 的區域。例如:us-central1europe-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

將要求主體儲存在名為 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 回應:

更新資料結構定義

REST 和指令列

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

本範例在要求網址中使用 ?updateMask=schemaDetails.type,schemaDetails.granularity。要求主體中包含 schemaDetails.typeschemaDetails.granularity 值,用於更新資料結構定義。

使用任何要求資料之前,請先替換以下項目:

  • REGIONALIZED_ENDPOINT:端點可能包含與 LOCATION_ID 相符的前置字串,例如 europe-west4-。進一步瞭解 地區化端點
  • PROJECT_NUMBER:您的 Google Cloud專案編號
  • LOCATION_ID:您使用 Vertex AI Vision 的區域。例如:us-central1europe-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

將要求主體儲存在名為 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"
    }
  }
}

列出語料庫中的資料結構定義

列出特定語料庫中的所有 DataSchema。回應會包含所有 DataSchema 資源,每個資源都有 DataSchema 資源名稱,可用於取得特定 DataSchema

REST

如要列出資料結構定義,請使用 projects.locations.corpora.dataSchemas.list 方法傳送 GET 要求。

使用任何要求資料之前,請先替換以下項目:

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

HTTP 方法和網址:

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

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas"

PowerShell

執行下列指令:

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

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應:

{
  "dataSchemas": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/KEY_STRING1",
      "key": "KEY_STRING1",
      "schemaDetails": {
        "type": "STRING",
        "granularity": "GRANULARITY_ASSET_LEVEL",
        "searchStrategy": {
          "searchStrategyType": "EXACT_SEARCH"
        }
      }
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/KEY_STRING2",
      "key": "KEY_STRING2",
      "schemaDetails": {
        "type": "PROTO_ANY",
        "granularity": "GRANULARITY_PARTITION_LEVEL",
        "protoAnyConfig": {
          "typeUri": "type.googleapis.com/google.cloud.visionai.v1.VideoActionRecognitionPredictionResult"
        },
        "searchStrategy": {
          "searchStrategyType": "SMART_SEARCH"
        }
      }
    }
  ]
}

取得資料架構

取得特定 DataSchema 資源名稱的 DataSchema

REST

如要取得特定資料結構定義的詳細資料,請使用 projects.locations.corpora.dataSchemas.get 方法傳送 GET 要求。

使用任何要求資料之前,請先替換以下項目:

  • REGIONALIZED_ENDPOINT:端點可能包含與 LOCATION_ID 相符的前置字串,例如 europe-west4-。進一步瞭解 地區化端點
  • PROJECT_NUMBER:您的 Google Cloud專案編號
  • LOCATION_ID:您使用 Vertex AI Vision 的區域。例如:us-central1europe-west4。請參閱可用區域
  • CORPUS_ID:目標語料庫的 ID。
  • DATASCHEMA_ID:目標資料結構定義的 ID。

HTTP 方法和網址:

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

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID"

PowerShell

執行下列指令:

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

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/KEY_STRING",
  "key": "KEY_STRING",
  "schemaDetails": {
    "type": "STRING",
    "granularity": "GRANULARITY_ASSET_LEVEL",
    "searchStrategy": {
      "searchStrategyType": "EXACT_SEARCH"
    }
  }
}

刪除資料架構

REST 和指令列

下列程式碼範例使用 projects.locations.corpora.dataSchemas.delete 方法刪除倉庫 dataSchema

使用任何要求資料之前,請先替換以下項目:

  • REGIONALIZED_ENDPOINT:端點可能包含與 LOCATION_ID 相符的前置字串,例如 europe-west4-。進一步瞭解 地區化端點
  • PROJECT_NUMBER:您的 Google Cloud專案編號
  • LOCATION_ID:您使用 Vertex AI Vision 的區域。例如:us-central1europe-west4。請參閱可用區域
  • CORPUS_ID:目標語料庫的 ID。
  • DATASCHEMA_ID:目標資料結構定義的 ID。

HTTP 方法和網址:

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

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID"

PowerShell

執行下列指令:

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

Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應:

{}

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

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

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

控制台

  1. 開啟 Vertex AI Vision 資訊主頁的「倉庫」分頁。

    前往「倉庫」分頁

  2. 找出倉庫語料庫,然後選取其名稱。 「倉庫詳細資料」頁面隨即顯示。

  3. 選取要啟用搜尋功能的欄位。

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