管理注释

借助 Vision Warehouse API，您可以使用命令行管理 Vision Warehouse 资源。

数据提取部署应用中的关联仓库 (corpus) 包含一个或多个媒体对象（例如视频资源）。这些媒体对象（asset 资源）包含元数据和资源注释 (annotations)。根据媒体对象上使用的模型，这些注释可以包含不同类型的信息，例如标签、边界框和时间戳。

您可以使用以下命令来管理这些注释。

注释分为两种类型：

  1. 素材资源级注解：应用于整个素材资源的注解。 例如：camera-location。
  2. 分区级注解：仅应用于部分资产的注解。您必须为流式视频资源指定时间分区（开始时间和结束时间），或为批处理视频资源指定相对时间分区（开始偏移量或结束偏移量），才能获取分区级注解信息。

在创建注解之前，您必须创建相应的数据架构，并使用相同的键来指明注解的值的数据类型。 如果您需要更改特定键的值类型，则必须删除使用此键的所有注释。删除这些注释后，您可以更新相应的数据架构。

创建仓库资产注解

您必须先完成以下步骤，然后才能为媒体资源创建注解：

  • 在数据仓库中创建 asset 资源。
  • 创建具有相同键的 dataSchema 资源，以指明 annotation 值的数据类型。

annotation 资源可以选择性地关联一个时间分区。例如，如果注解适用于整个视频素材资源，您可以省略与其关联的任何时间分区。同样，如果注解仅适用于视频素材资源的特定部分，您可以在创建 annotation 资源时提供素材资源的时间范围。

创建不含时间分区的注解

如果注解适用于整个视频素材资源，您无需为其提供时间分区。使用以下示例为整个素材资源（未指定视频时间段）创建 annotation 资源。

REST

在使用任何请求数据之前，请先进行以下替换：

  • 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。
  • ANNOTATION_ID：（可选）用户提供的注解 ID 值。在此请求中，该值会以以下形式添加到请求网址中：
    • https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_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": "camera-location",
    "value": {
      "str_value": "Sunnyvale"
    }
  }
}

如需发送请求，请选择以下方式之一：

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": "camera-location",
    "value": {
      "strValue": "Sunnyvale"
    }
  }
}

创建具有时间分区的注解

如果注解仅适用于流式视频素材资源的一部分，您可以为目标视频部分提供时间范围。使用以下示例，通过时间分区为视频资产的特定时间段创建 annotation 资源。

REST

在使用任何请求数据之前，请先进行以下替换：

  • 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。
  • ANNOTATION_ID：（可选）用户提供的注解 ID 值。在此请求中，该值会以以下形式添加到请求网址中：
    • https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_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": "object-detected",
    "value": {
      "str_value": "cat"
    },
    "partition": {
      "temporal_partition": {
        "start_time": {
          "seconds": "1630464728"
        },
        "end_time": {
          "seconds": "1630464729"
        }
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

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": "object-detected",
    "value": {
      "strValue": "cat"
    },
    "partition": {
      "temporalPartition": {
        "startTime": "2022-09-14T20:33:09Z",
        "endTime": "2022-09-14T20:33:39Z"
      }
    }
  }
}

创建具有相对时间分区的注解

如果注解仅适用于批量视频素材资源的一部分，您可以为目标视频部分提供时间范围。使用以下示例，通过相对时间分区为视频素材资源的特定时间段创建 annotation 资源。

REST

在使用任何请求数据之前，请先进行以下替换：

  • 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。
  • ANNOTATION_ID：（可选）用户提供的注解 ID 值。在此请求中，该值会以以下形式添加到请求网址中：
    • https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_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": "object-detected",
    "value": {
      "str_value": "cat"
    },
    "partition": {
      "relative_temporal_partition": {
        "start_offset": {
          "seconds": "60"
        },
        "end_offset": {
          "seconds": "300"
        }
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

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": "object-detected",
    "value": {
      "strValue": "cat"
    },
    "partition": {
      "relative_temporal_partition": {
        "start_offset": "60s",
        "end_offset": "300s"
      }
    }
  }
}

更新注解（无时间分区）

REST

在使用任何请求数据之前，请先进行以下替换：

  • 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。
  • ANNOTATION_ID：目标注解的 ID。

HTTP 方法和网址：

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

请求 JSON 正文： 

{
 "user_specified_annotation":{
    "key": "camera-location",
    "value": {
      "str_value": "UPDATED_FIELD_VALUE"
    }
  }
}

如需发送请求，请选择以下方式之一：

curl