Web Hooks - Create

服務:
Azure AI Services
API 版本:
v3.2-preview.2

建立新的 Web 攔截。
如果組態中的屬性密碼存在且包含非空白字串，則會用來建立承載的SHA256哈希，並將秘密作為HMAC金鑰。 回呼至已註冊的 URL 時，此哈希會設定為 X-MicrosoftSpeechServices-Signature 標頭。

回呼至已註冊的 URL 時，要求會包含 X-MicrosoftSpeechServices-Event 標頭，其中包含其中一個已註冊的事件類型。 每個已註冊的事件類型將會有一個要求。

成功註冊 Web 攔截之後，在完成挑戰/回應之前，將無法使用。 若要這樣做，將會使用名為 validationToken 的查詢參數來提出具有事件類型挑戰的要求。 以 200 OK 回應挑戰，其中包含 validationToken 查詢參數的值做為回應本文。 成功完成挑戰/回應時，Web 攔截會開始接收事件。

POST {endpoint}/speechtotext/v3.2-preview.2/webhooks

URI 參數

名稱 位於 必要 類型 Description
endpoint
 path True

string

支援的認知服務端點（通訊協定和主機名，例如：https://westus.api.cognitive.microsoft.com）。

要求本文

名稱 必要 類型 Description
displayName True

string

minLength: 1

對象的顯示名稱。
events True

WebHookEvents

WebHookEvents
webUrl True

string (uri)

將用來將已註冊事件的POST要求傳送至的已註冊URL。
customProperties

object

此實體的自定義屬性。 允許的索引鍵長度上限為 64 個字元，允許的最大值長度為 256 個字元，允許的項目計數為 10。
description

string

物件的描述。
properties

WebHookProperties

WebHookProperties

回應

名稱 類型 Description
201 Created

WebHook

回應包含實體作為承載的相關信息，以及其位置作為標頭。

標題

Location: string
Other Status Codes

Error

發生錯誤。

安全性

Ocp-Apim-Subscription-Key

在這裡提供您的認知服務帳戶金鑰。

類型: apiKey
位於: header

Authorization

提供來自此區域 STS 所傳回之 JWT 的存取令牌。 請務必將下列查詢字串新增至 STS URL，將管理範圍新增至令牌：？scope=speechservicesmanagement

類型: apiKey
位於: header

範例

Create a web hook

範例要求

POST {endpoint}/speechtotext/v3.2-preview.2/webhooks

{
  "displayName": "TranscriptionCompletionWebHook",
  "properties": {
    "secret": "$CREDENTIAL_PLACEHOLDER$"
  },
  "webUrl": "https://contoso.com/call/me/back",
  "events": {
    "transcriptionCompletion": true
  },
  "description": "I registered this URL to get a POST request for each completed transcription."
}

範例回覆

狀態碼:
201 
Location: https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d
{
  "displayName": "TranscriptionCompletionWebHook",
  "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d",
  "links": {
    "ping": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d:test",
    "test": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d:ping"
  },
  "properties": {
    "apiVersion": "v3.2-preview.2",
    "secret": "$CREDENTIAL_PLACEHOLDER$"
  },
  "webUrl": "https://contoso.com/call/me/back",
  "events": {
    "transcriptionCompletion": true
  },
  "description": "I registered this URL to get a POST request for each completed transcription.",
  "createdDateTime": "2018-11-11T00:00:00Z",
  "lastActionDateTime": "2018-11-28T00:00:00Z",
  "status": "NotStarted"
}

定義

名稱 Description
DetailedErrorCode

DetailedErrorCode
EntityError

EntityError
Error

錯誤
ErrorCode

錯誤代碼
InnerError

InnerError
Status

地位
WebHook

WebHook
WebHookEvents

WebHookEvents
WebHookLinks

WebHookLinks
WebHookProperties

WebHookProperties

DetailedErrorCode

列舉型別

DetailedErrorCode

值 Description
InvalidParameterValue

無效的參數值。
InvalidRequestBodyFormat

要求本文格式無效。
EmptyRequest

空白要求。
MissingInputRecords

遺漏輸入記錄。
InvalidDocument

無效的檔。
ModelVersionIncorrect

模型版本不正確。
InvalidDocumentBatch

檔批次無效。
UnsupportedLanguageCode

不支援的語言代碼。
DataImportFailed

數據匯入失敗。
InUseViolation

在使用違規中。
InvalidLocale

地區設定無效。
InvalidBaseModel

基底模型無效。
InvalidAdaptationMapping

無效的適應對應。
InvalidDataset

無效的數據集。
InvalidTest

無效的測試。
FailedDataset

失敗的數據集。
InvalidModel

無效的模型。
InvalidTranscription

無效的轉譯。
InvalidPayload

無效的承載。
InvalidParameter

無效的參數。
EndpointWithoutLogging

沒有記錄的端點。
InvalidPermissions

許可權無效。
InvalidPrerequisite

無效的必要條件。
InvalidProductId

無效的產品標識碼。
InvalidSubscription

無效的訂用帳戶。
InvalidProject

無效的專案。
InvalidProjectKind

無效的項目種類。
InvalidRecordingsUri

無效的錄製 URI。
OnlyOneOfUrlsOrContainerOrDataset

只有一個 URL 或容器或數據集。
ExceededNumberOfRecordingsUris

超過錄製 URI 的數目。
ModelMismatch

模型不符。
ProjectGenderMismatch

專案性別不符。
ModelDeprecated

模型已被取代。
ModelExists

模型存在。
ModelNotDeployable

模型不可部署。
EndpointNotUpdatable

端點無法更新。
SingleDefaultEndpoint

單一預設端點。
EndpointCannotBeDefault

端點不可為預設值。
InvalidModelUri

無效的模型 URI。
SubscriptionNotFound

找不到訂用帳戶。
QuotaViolation

配額違規。
UnsupportedDelta

不支持的差異。
UnsupportedFilter

不支援的篩選。
UnsupportedPagination

不支援的分頁。
UnsupportedDynamicConfiguration

不支援的動態設定。
UnsupportedOrderBy

不支援的順序依據。
NoUtf8WithBom

沒有 utf8 與 bom。
ModelDeploymentNotCompleteState

模型部署未完成狀態。
SkuLimitsExist

Sku 限制存在。
DeployingFailedModel

部署失敗的模型。
UnsupportedTimeRange

不支援的時間範圍。
InvalidLogDate

無效的記錄日期。
InvalidLogId

無效的記錄標識碼。
InvalidLogStartTime

無效的記錄開始時間。
InvalidLogEndTime

無效的記錄結束時間。
InvalidTopForLogs

記錄的頂端無效。
InvalidSkipTokenForLogs

記錄的略過令牌無效。
DeleteNotAllowed

不允許刪除。
Forbidden

禁止。
DeployNotAllowed

不允許部署。
UnexpectedError

未預期的錯誤。
InvalidCollection

無效的集合。
InvalidCallbackUri

無效的回呼 URI。
InvalidSasValidityDuration

無效的 sas 有效性持續時間。
InaccessibleCustomerStorage

無法存取的客戶記憶體。
UnsupportedClassBasedAdaptation

不支援的類別型調整。
InvalidWebHookEventKind

無效的 Web 攔截事件種類。
InvalidTimeToLive

存留時間無效。
InvalidSourceAzureResourceId

來源 Azure 資源標識碼無效。
ModelCopyOperationExists

模型複製作業存在。

EntityError

Object

EntityError

名稱 類型 Description
code

string

此錯誤的程序代碼。
message

string

此錯誤的訊息。

Error

Object

錯誤

名稱 類型 Description
code

ErrorCode

錯誤代碼
高階錯誤碼。
details

Error[]

有關錯誤和/或預期原則的其他支持詳細數據。
innerError

InnerError

InnerError
符合認知服務 API 指導方針的新內部錯誤格式，可在 https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow取得。 這包括必要的屬性 ErrorCode、訊息和選擇性屬性目標、details（索引鍵值組）、內部錯誤（這可以是巢狀的）。
message

string

高階錯誤訊息。
target

string

錯誤的來源。 例如，如果檔無效，則會是「檔」或「文件標識碼」。

ErrorCode

列舉型別

錯誤代碼

值 Description
InvalidRequest

表示無效的要求錯誤碼。
InvalidArgument

表示無效的自變數錯誤碼。
InternalServerError

表示內部伺服器錯誤碼。
ServiceUnavailable

表示服務無法使用的錯誤碼。
NotFound

表示找不到的錯誤碼。
PipelineError

表示管線錯誤碼。
Conflict

表示衝突錯誤碼。
InternalCommunicationFailed

表示內部通訊失敗的錯誤碼。
Forbidden

表示禁止的錯誤碼。
NotAllowed

表示不允許的錯誤碼。
Unauthorized

表示未經授權的錯誤碼。
UnsupportedMediaType

表示不支援的媒體類型錯誤碼。
TooManyRequests

表示太多要求錯誤碼。
UnprocessableEntity

表示無法處理的實體錯誤碼。

InnerError

Object

InnerError

名稱 類型 Description
code

DetailedErrorCode

DetailedErrorCode
詳細的錯誤碼列舉。
details

object

有關錯誤和/或預期原則的其他支持詳細數據。
innerError

InnerError

InnerError
符合認知服務 API 指導方針的新內部錯誤格式，可在 https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow取得。 這包括必要的屬性 ErrorCode、訊息和選擇性屬性目標、details（索引鍵值組）、內部錯誤（這可以是巢狀的）。
message

string

高階錯誤訊息。
target

string

錯誤的來源。 例如，如果檔無效，則會是「檔」或「文件標識碼」。

Status

列舉型別

地位

值 Description
NotStarted

長時間執行的作業尚未啟動。
Running

長時間執行的作業目前正在處理中。
Succeeded

長時間執行的作業已順利完成。
Failed

長時間執行的作業失敗。

WebHook

Object

WebHook

名稱 類型 Description
createdDateTime

string (date-time)

物件建立時的時間戳。 時間戳會編碼為 ISO 8601 日期和時間格式（“YYYY-MM-DDThh：mm：ssZ”，請參閱 https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations）。
customProperties

object

此實體的自定義屬性。 允許的索引鍵長度上限為 64 個字元，允許的最大值長度為 256 個字元，允許的項目計數為 10。
description

string

物件的描述。
displayName

string

minLength: 1

對象的顯示名稱。
events

WebHookEvents

WebHookEvents
lastActionDateTime

string (date-time)

輸入目前狀態時的時間戳。 時間戳會編碼為 ISO 8601 日期和時間格式（“YYYY-MM-DDThh：mm：ssZ”，請參閱 https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations）。
links

WebHookLinks

WebHookLinks
properties

WebHookProperties

WebHookProperties
self

string (uri)

此實體的位置。
status

Status

地位
描述 API 的目前狀態
webUrl

string (uri)

將用來將已註冊事件的POST要求傳送至的已註冊URL。

WebHookEvents

Object

WebHookEvents

名稱 類型 Description
challenge

boolean

datasetCompletion

boolean

datasetCreation

boolean

datasetDeletion

boolean

datasetProcessing

boolean

endpointCompletion

boolean

endpointCreation

boolean

endpointDeletion

boolean

endpointProcessing

boolean

evaluationCompletion

boolean

evaluationCreation

boolean

evaluationDeletion

boolean

evaluationProcessing

boolean

modelCompletion

boolean

modelCreation

boolean

modelDeletion

boolean

modelProcessing

boolean

ping

boolean

transcriptionCompletion

boolean

transcriptionCreation

boolean

transcriptionDeletion

boolean

transcriptionProcessing

boolean

Object

WebHookLinks

名稱 類型 Description
ping

string (uri)

URL，可用來觸發將 Ping 事件傳送至 Web 攔截註冊的已註冊 URL。 如需詳細資訊，請參閱作業「WebHooks_Ping」。
test

string (uri)

URL，可用來將測試事件傳送至 Web 攔截註冊的已註冊 URL。 如需詳細資訊，請參閱作業「WebHooks_Test」。

WebHookProperties

Object

WebHookProperties

名稱 類型 Description
apiVersion

string

建立 Web 攔截的 API 版本。 這會在回呼中定義承載的形狀。 如果不再支持承載類型，因為圖形已變更，且使用它的API版本已移除（取代之後），將會停用Web攔截。
error

EntityError

EntityError
secret

string

秘密，將用來建立承載的SHA256哈希，並將秘密作為 HMAC 密鑰。 回呼至已註冊的 URL 時，此哈希會設定為 X-MicrosoftSpeechServices-Signature 標頭。