影片擷取 API 參考

驗證

在此文件中呼叫任何 API 時，請包含下列標頭。

Ocp-Apim-Subscription-Key：版本： YOUR_COMPUTER_VISION_KEY2023-05-01-preview

CreateIndex

URL

PUT /retrieval/indexes/{indexName}?api-version=<version_number>

描述

這個方法會建立索引，然後可用來內嵌檔。 必須先建立索引，才能執行擷取。

參數

名稱	位於	描述	必要	類型
indexName	path	要建立之索引的名稱。	Yes	字串
api-version	query	要求的 API 版本。	Yes	字串
body	body	包含可用於搜尋之元數據的要求本文。	Yes	CreateIngestionIndexRequestModel

回覆

代碼	Description	類型
201	建立時間	GetIngestionIndexResponseModel

GetIndex

URL

GET /retrieval/indexes/{indexName}?api-version=<version_number>

描述

擷取具有指定名稱的索引。

參數

名稱	位於	描述	必要	類型
indexName	path	要擷取的索引名稱。	Yes	字串
api-version	query	要求的 API 版本。	Yes	字串

回覆

代碼	Description	類型
200	成功	GetIngestionIndexResponseModel
default	錯誤	ErrorResponse

UpdateIndex

URL

PATCH /retrieval/indexes/{indexName}?api-version=<version_number>

描述

使用指定的名稱更新索引。

參數

名稱	位於	描述	必要	類型
indexName	path	要更新之索引的名稱。	Yes	字串
api-version	query	要求的 API 版本。	Yes	字串
body	body	包含要套用至索引之更新的要求本文。	Yes	UpdateIngestionIndexRequestModel

回覆

代碼	Description	類型
200	成功	GetIngestionIndexResponseModel
default	錯誤	ErrorResponse

DeleteIndex

URL

DELETE /retrieval/indexes/{indexName}?api-version=<version_number>

描述

刪除索引及其所有相關聯的擷取檔。

參數

名稱	位於	描述	必要	類型
indexName	path	要刪除的索引名稱。	Yes	字串
api-version	query	要求的 API 版本。	Yes	字串

回覆

代碼	描述
204	沒有內容

ListIndexes

URL

GET /retrieval/indexes?api-version=<version_number>

描述

擷取所有擷取的所有索引清單。

參數

名稱	位於	描述	必要	類型
$skip	query	要略過的數據集數目。	No	整數
$top	query	略過之後要傳回的數據集數目。	No	整數
api-version	query	要求的 API 版本。	Yes	字串

回覆

代碼	Description	類型
200	成功	GetIngestionIndexResponseModelCollectionApiModel
default	錯誤	ErrorResponse

CreateIngestion

URL

PUT /retrieval/indexes/{indexName}/ingestions/{ingestionName}?api-version=<version_number>

描述

擷取要求可以有視訊承載。 它可以有三種模式之一（新增、更新或移除）。 新增模式會建立擷取並處理影片。 更新模式只會更新元數據。 若要重新處理影片，必須刪除並重新建立擷取。

參數

名稱	位於	描述	必要	類型
indexName	path	要建立擷取的索引名稱。	Yes	字串
ingestionName	path	要建立之擷取的名稱。	Yes	字串
api-version	query	要求的 API 版本。	Yes	字串
body	body	包含要建立之擷取要求的要求主體。	Yes	CreateIngestionRequestModel

回覆

代碼	Description	類型
202	已接受	IngestionResponseModel

GetIngestion

URL

GET /retrieval/indexes/{indexName}/ingestions/{ingestionName}?api-version=<version_number>

描述

取得指定索引和擷取名稱的擷取狀態。

參數

名稱	位於	描述	必要	類型
indexName	path	要檢查擷取狀態的索引名稱。	Yes	字串
ingestionName	path	要擷取的擷取名稱。	Yes	字串
detailLevel	query	指出每個檔擷取狀態詳細數據層級的層級。	No	字串
api-version	query	要求的 API 版本。	Yes	字串

回覆

代碼	Description	類型
200	成功	IngestionResponseModel
default	錯誤	ErrorResponse

ListIngestions

URL

GET /retrieval/indexes/{indexName}/ingestions?api-version=<version_number>

描述

擷取特定索引的所有擷取。

參數

名稱	位於	描述	必要	類型
indexName	path	要擷取擷取之索引的名稱。	Yes	字串
api-version	query	要求的 API 版本。	Yes	字串

回覆

代碼	Description	類型
200	成功	IngestionResponseModelCollectionApiModel
default	錯誤	ErrorResponse

ListDocuments

URL

GET /retrieval/indexes/{indexName}/documents?api-version=<version_number>

描述

擷取特定索引的所有檔。

參數

名稱	位於	描述	必要	類型
indexName	path	要擷取檔之索引的名稱。	Yes	字串
$skip	query	要略過的數據集數目。	No	整數
$top	query	略過之後要傳回的數據集數目。	No	整數
api-version	query	要求的 API 版本。	Yes	字串

回覆

代碼	Description	類型
200	成功	IngestionDocumentResponseModelCollectionApiModel
default	錯誤	ErrorResponse

SearchByText

URL

POST /retrieval/indexes/{indexName}:queryByText?api-version=<version_number>

描述

在指定的索引上執行以文字為基礎的搜尋。

參數

名稱	位於	描述	必要	類型
indexName	path	要搜尋的索引名稱。	Yes	字串
api-version	query	要求的 API 版本。	Yes	字串
body	body	包含查詢和其他參數的要求主體。	Yes	SearchQueryTextRequestModel

回覆

代碼	Description	類型
200	成功	SearchResultDocumentModelCollectionApiModel
default	錯誤	ErrorResponse

模型

CreateIngestionIndexRequestModel

表示 JSON 檔的建立擷取索引要求模型。

名稱	類型​​	描述	必要
metadataSchema	MetadataSchemaModel		No
features	[ FeatureModel ]	取得或設定檔的功能清單。 預設值為 「視覺」。	No
userData	object	取得或設定檔的用戶數據。	No

CreateIngestionRequestModel

表示 JSON 檔的建立擷取要求模型。

名稱	類型​​	描述	必要
視頻	[ IngestionDocumentRequestModel ]	取得或設定 JSON 檔中的影片檔擷取要求清單。	No
仲裁	boolean	取得或設定仲裁旗標，指出是否應該仲裁內容。	No
generateInsightIntervals	boolean	取得或設定間隔產生旗標，指出是否應該產生深入解析間隔。	No
documentAuthenticationKind	字串	取得或設定要用於下載檔的驗證種類。 列舉："none"、"managedIdentity"	No
filterDefectedFrames	boolean	畫面格篩選旗標，指出畫面格會被評估，且所有瑕疵畫面（例如模糊、低光、過度探索）畫面都會被篩選掉。	No
includeSpeechTranscript	boolean	取得或設定文字記錄產生旗標，指出是否應該產生文字記錄。	No

DatetimeFilterModel

表示要套用至搜尋查詢的日期時間篩選。

名稱	類型​​	描述	必要
fieldName	字串	取得或設定要篩選的功能變數名稱。	Yes
startTime	字串	取得或設定要篩選之範圍的開始時間。	No
endTime	字串	取得或設定要篩選之範圍的結束時間。	No

ErrorResponse

發生錯誤時傳回的回應。

名稱	類型​​	描述	必要
error	ErrorResponseDetails		Yes

ErrorResponseDetails

錯誤資訊。

名稱	類型​​	描述	必要
code	字串	錯誤碼。	Yes
message	字串	錯誤訊息。	Yes
目標	字串	錯誤的目標。	No
詳細資料	[ ErrorResponseDetails ]	詳細的錯誤清單。	No
innererror	ErrorResponseInnerError		No

ErrorResponseInnerError

詳細的錯誤。

名稱	類型​​	描述	必要
code	字串	錯誤碼。	Yes
message	字串	錯誤訊息。	Yes
innererror	ErrorResponseInnerError		No

FeatureModel

表示索引中的功能。

名稱	類型​​	描述	必要
NAME	字串	取得或設定功能的名稱。 列舉："vision"、"speech"	Yes
modelVersion	字串	取得或設定功能的模型版本。	No
網域	字串	取得或設定功能的模型定義域。 列舉："generic"、"surveillance"	No

GetIngestionIndexResponseModel

表示 JSON 檔的取得擷取索引回應模型。

名稱	類型​​	描述	必要
NAME	字串	取得或設定索引名稱屬性。	No
metadataSchema	MetadataSchemaModel		No
userData	object	取得或設定檔的用戶數據。	No
features	[ FeatureModel ]	取得或設定索引中的功能清單。	No
eTag	字串	取得或設定 etag。	Yes
createdDateTime	dateTime	取得或設定建立的日期和時間屬性。	Yes
lastModifiedDateTime	dateTime	取得或設定上次修改的日期和時間屬性。	Yes

GetIngestionIndexResponseModelCollectionApiModel

包含可能分頁的結果陣列。

名稱	類型​​	描述	必要
value	[ GetIngestionIndexResponseModel ]	結果的陣列。	Yes
nextLink	字串	如果有更多可用的結果，則為下一組編頁結果的連結;否則不會存在。	No

IngestionDocumentRequestModel

表示 JSON 檔中的影片檔擷取要求。

名稱	類型​​	描述	必要
mode	字串	取得或設定檔的擷取模式。 列舉："add"、、"update"、"remove"	Yes
documentId	字串	取得或設定文件識別碼。	No
documentUrl	字串 (URI)	取得或設定檔URL。 共用存取簽章（SAS），如果有的話，將會從URL中移除。	Yes
中繼資料	object	取得或設定檔的元數據，做為名稱/值組的字典。	No
userData	object	取得或設定檔的用戶數據。	No

IngestionDocumentResponseModel

表示 JSON 檔中的擷取檔回應物件。

名稱	類型​​	描述	必要
documentId	字串	取得或設定文件識別碼。	No
documentUrl	字串 (URI)	取得或設定檔URL。 共用存取簽章（SAS），如果有的話，將會從URL中移除。	No
中繼資料	object	取得或設定元數據的索引鍵/值組。	No
error	ErrorResponseDetails		No
createdDateTime	dateTime	取得或設定檔的建立日期和時間。	No
lastModifiedDateTime	dateTime	取得或設定檔上次修改的日期和時間。	No
userData	object	取得或設定檔的用戶數據。	No

IngestionDocumentResponseModelCollectionApiModel

包含可能分頁的結果陣列。

名稱	類型​​	描述	必要
value	[ IngestionDocumentResponseModel ]	結果的陣列。	Yes
nextLink	字串	如果有更多可用的結果，則為下一組編頁結果的連結;否則不會存在。	No

IngestionErrorDetailsApiModel

代表每個文件的擷取錯誤資訊。

名稱	類型​​	描述	必要
code	字串	錯誤碼。	No
message	字串	錯誤訊息。	No
innerError	IngestionInnerErrorDetailsApiModel		No

IngestionInnerErrorDetailsApiModel

代表每個文件的擷取內部錯誤資訊。

名稱	類型​​	描述	必要
code	字串	錯誤碼。	No
message	字串	錯誤訊息。	No
innerError	IngestionInnerErrorDetailsApiModel		No

IngestionResponseModel

表示 JSON 檔的擷取回應模型。

名稱	類型​​	描述	必要
NAME	字串	取得或設定擷取的名稱。	No
state	字串	取得或設定擷取的狀態。 列舉："notStarted"、、、"running""completed"、"failed"、"partiallySucceeded"	No
error	ErrorResponseDetails		No
batchName	字串	與此擷取相關聯的批次名稱。	No
createdDateTime	dateTime	取得或設定擷取的建立日期和時間。	No
lastModifiedDateTime	dateTime	取得或設定擷取的上次修改日期和時間。	No
fileStatusDetails	[ IngestionStatusDetailsApiModel ]	每個檔案的擷取狀態清單。	No

IngestionResponseModelCollectionApiModel

包含可能分頁的結果陣列。

名稱	類型​​	描述	必要
value	[ IngestionResponseModel ]	結果的陣列。	Yes
nextLink	字串	如果有更多可用的結果，則為下一組編頁結果的連結;否則不會存在。	No

IngestionStatusDetailsApiModel

代表每個文件的擷取狀態詳細數據。

名稱	類型​​	描述	必要
lastUpdateTime	dateTime	批次區塊的狀態更新時間。	Yes
documentId	字串	文件識別碼。	Yes
documentUrl	字串 (URI)	檔的 URL。	No
succeeded	boolean	旗標，指出推斷是否成功。	Yes
error	IngestionErrorDetailsApiModel		No

MetadataSchemaFieldModel

表示元數據架構中的欄位。

名稱	類型​​	描述	必要
NAME	字串	取得或設定欄位的名稱。	Yes
可搜尋	boolean	取得或設定值，指出欄位是否可搜尋。	Yes
可篩選	boolean	取得或設定值，指出欄位是否可篩選。	Yes
type	字串	取得或設定欄位的類型。 它可以是字串或日期時間。 列舉："string"、"datetime"	Yes

MetadataSchemaModel

表示檔的元數據架構。

名稱	類型​​	描述	必要
language	字串	取得或設定元數據架構的語言。 預設值為 「en」。	No
欄位	[ MetadataSchemaFieldModel ]	取得或設定元數據架構中的欄位清單。	Yes

SearchFiltersModel

表示要套用至搜尋查詢的篩選。

名稱	類型​​	描述	必要
stringFilters	[ StringFilterModel ]	取得或設定要套用至搜尋查詢的字串篩選條件。	No
datetimeFilters	[ DatetimeFilterModel ]	取得或設定要套用至搜尋查詢的日期時間篩選。	No
featureFilters	[ string ]	取得或設定要套用至搜尋查詢的功能篩選。	No

SearchQueryTextRequestModel

表示文字型搜尋的搜尋查詢要求模型。

名稱	類型​​	描述	必要
queryText	字串	取得或設定查詢文字。	Yes
篩選	SearchFiltersModel		No
仲裁	boolean	取得或設定布爾值，指出是否啟用或停用仲裁。	No
熱門	整數	取得或設定要擷取的結果數目。	Yes
skip	整數	取得或設定要略過的結果數目。	Yes
additionalIndexNames	[ string ]	取得或設定要包含在搜尋查詢中的其他索引名稱。	No
dedup	boolean	是否要移除類似的視訊畫面。	Yes
dedupMaxDocumentCount	整數	重複資料刪除后的檔數目上限。	Yes
disableMetadataSearch	boolean	取得或設定布爾值，指出是否在搜尋中停用元數據。	Yes

SearchResultDocumentModel

表示搜尋查詢回應。

名稱	類型​​	描述	必要
documentId	字串	取得或設定文件的識別碼。	No
documentKind	字串	取得或設定檔種類，可以是「視訊」。	No
start	字串	取得或設定檔的開始時間。 此屬性僅適用於影片檔。	No
end	字串	取得或設定檔的結束時間。 此屬性僅適用於影片檔。	No
最佳	字串	取得或設定具有最高相關性分數的文件時間戳。 此屬性僅適用於影片檔。	No
關聯	double	取得或設定文件的相關性分數。	Yes
additionalMetadata	object	取得或設定與搜尋相關的其他元數據。	No

SearchResultDocumentModelCollectionApiModel

包含可能分頁的結果陣列。

名稱	類型​​	描述	必要
value	[ SearchResultDocumentModel ]	結果的陣列。	Yes
nextLink	字串	如果有更多可用的結果，則為下一組編頁結果的連結;否則不會存在。	No

StringFilterModel

表示要套用至搜尋查詢的字串篩選。

名稱	類型​​	描述	必要
fieldName	字串	取得或設定要篩選的功能變數名稱。	Yes
值	[ string ]	取得或設定要篩選的值。	Yes

UpdateIngestionIndexRequestModel

表示 JSON 檔的更新擷取索引要求模型。

名稱	類型​​	描述	必要
metadataSchema	MetadataSchemaModel		No
userData	object	取得或設定檔的用戶數據。	No