Create Hook - Create Hook
创建新的 Web 挂钩。
如果配置中的属性机密存在并包含非空字符串,则它将用于创建有效负载的 SHA256 哈希,并将机密用作 HMAC 密钥。 调用回注册的 URL 时,此哈希将设置为 X-MicrosoftSpeechServices-Signature 标头。
当调用回注册的 URL 时,请求将包含包含其中一个已注册事件类型的 X-MicrosoftSpeechServices-Event 标头。 每个已注册的事件类型将有一个请求。
成功注册 Web 挂钩后,在完成质询/响应之前,它将无法使用。 为此,将使用名为 validationToken 的查询参数发出具有事件类型质询的请求。 使用包含 validationToken 查询参数的值作为响应正文的 200 OK 响应质询。 成功完成质询/响应后,Web 挂钩将开始接收事件。
POST {Endpoint}/speechtotext/v3.0/webhooks
URI 参数
名称 | 在 | 必需 | 类型 | 说明 |
---|---|---|---|---|
Endpoint
|
path | True |
string |
支持的认知服务终结点(协议和主机名,例如:https://westus.api.cognitive.microsoft.com)。 |
请求正文
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
displayName | True |
string |
对象的显示名称。 |
events | True |
WebHookEvents |
|
webUrl | True |
string (uri) |
用于将已注册事件的 POST 请求发送到的已注册 URL。 |
customProperties |
object |
此实体的自定义属性。 允许的最大密钥长度为 64 个字符,允许的最大值长度为 256 个字符,允许的条目计数为 10。 |
|
description |
string |
对象的说明。 |
|
links |
WebHookLinks |
||
properties |
WebHookProperties |
响应
名称 | 类型 | 说明 |
---|---|---|
201 Created |
响应包含有关实体作为有效负载的信息及其作为标头的位置。 标头 Location: string |
|
Other Status Codes |
发生错误。 |
安全性
Ocp-Apim-Subscription-Key
在此处提供认知服务帐户密钥。
类型:
apiKey
在:
header
Authorization
提供来自此区域的 STS 返回的 JWT 的访问令牌。 通过将以下查询字符串添加到 STS URL,确保将管理范围添加到令牌: ?scope=speechservicesmanagement
类型:
apiKey
在:
header
示例
Create a web hook
示例请求
POST https://westus.api.cognitive.microsoft.com//speechtotext/v3.0/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."
}
示例响应
Location: https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d
{
"displayName": "TranscriptionCompletionWebHook",
"self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d",
"links": {
"ping": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/hooks/2e856efe-ef53-465a-a632-6a084c1d349d/test",
"test": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.0/hooks/2e856efe-ef53-465a-a632-6a084c1d349d/ping"
},
"properties": {
"apiVersion": "v3.0",
"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"
}
定义
名称 | 说明 |
---|---|
Detailed |
DetailedErrorCode |
Entity |
EntityError |
Error |
错误 |
Error |
ErrorCode |
Inner |
InnerError |
Status |
地位 |
Web |
WebHook |
Web |
WebHookEvents |
Web |
WebHookLinks |
Web |
WebHookProperties |
DetailedErrorCode
DetailedErrorCode
值 | 说明 |
---|---|
DataImportFailed |
数据导入失败。 |
DeleteNotAllowed |
不允许删除。 |
DeployNotAllowed |
不允许部署。 |
DeployingFailedModel |
部署失败的模型。 |
EmptyRequest |
空请求。 |
EndpointCannotBeDefault |
终结点不能为默认值。 |
EndpointNotUpdatable |
终结点不可更新。 |
EndpointWithoutLogging |
没有日志记录的终结点。 |
ExceededNumberOfRecordingsUris |
超过录制 URI 数。 |
FailedDataset |
失败的数据集。 |
Forbidden |
禁止。 |
InUseViolation |
在使用冲突中。 |
InaccessibleCustomerStorage |
无法访问客户存储。 |
InvalidAdaptationMapping |
适应映射无效。 |
InvalidBaseModel |
基本模型无效。 |
InvalidCallbackUri |
回调 URI 无效。 |
InvalidCollection |
集合无效。 |
InvalidDataset |
数据集无效。 |
InvalidDocument |
无效的文档。 |
InvalidDocumentBatch |
文档批处理无效。 |
InvalidLocale |
区域设置无效。 |
InvalidLogDate |
日志日期无效。 |
InvalidLogEndTime |
日志结束时间无效。 |
InvalidLogId |
无效的日志 ID。 |
InvalidLogStartTime |
无效的日志开始时间。 |
InvalidModel |
无效的模型。 |
InvalidModelUri |
模型 URI 无效。 |
InvalidParameter |
参数无效。 |
InvalidParameterValue |
参数值无效。 |
InvalidPayload |
有效负载无效。 |
InvalidPermissions |
权限无效。 |
InvalidPrerequisite |
先决条件无效。 |
InvalidProductId |
产品 ID 无效。 |
InvalidProject |
项目无效。 |
InvalidProjectKind |
项目类型无效。 |
InvalidRecordingsUri |
录制 URI 无效。 |
InvalidRequestBodyFormat |
请求正文格式无效。 |
InvalidSasValidityDuration |
SAS 有效期无效。 |
InvalidSkipTokenForLogs |
日志的跳过令牌无效。 |
InvalidSubscription |
订阅无效。 |
InvalidTest |
测试无效。 |
InvalidTimeToLive |
生存时间无效。 |
InvalidTopForLogs |
日志顶部无效。 |
InvalidTranscription |
听录无效。 |
InvalidWebHookEventKind |
Web 挂钩事件类型无效。 |
MissingInputRecords |
缺少输入记录。 |
ModelDeploymentNotCompleteState |
模型部署未完成状态。 |
ModelDeprecated |
模型已弃用。 |
ModelExists |
模型存在。 |
ModelMismatch |
模型不匹配。 |
ModelNotDeployable |
模型不可部署。 |
ModelVersionIncorrect |
模型版本不正确。 |
NoUtf8WithBom |
没有带有 bom 的 utf8。 |
OnlyOneOfUrlsOrContainerOrDataset |
只有一个 URL 或容器或数据集。 |
ProjectGenderMismatch |
项目性别不匹配。 |
QuotaViolation |
配额冲突。 |
SingleDefaultEndpoint |
单个默认终结点。 |
SkuLimitsExist |
SKU 限制存在。 |
SubscriptionNotFound |
找不到订阅。 |
UnexpectedError |
意外错误。 |
UnsupportedClassBasedAdaptation |
不支持的基于类的适应。 |
UnsupportedDelta |
不支持的增量。 |
UnsupportedDynamicConfiguration |
不支持的动态配置。 |
UnsupportedFilter |
不支持的筛选器。 |
UnsupportedLanguageCode |
不支持的语言代码。 |
UnsupportedOrderBy |
不受支持的订单依据。 |
UnsupportedPagination |
不支持的分页。 |
UnsupportedTimeRange |
不支持的时间范围。 |
EntityError
EntityError
名称 | 类型 | 说明 |
---|---|---|
code |
string |
此错误的代码。 |
message |
string |
此错误的消息。 |
Error
错误
名称 | 类型 | 说明 |
---|---|---|
code |
ErrorCode |
|
details |
Error[] |
有关错误和/或预期策略的其他支持详细信息。 |
innerError |
InnerError |
|
message |
string |
高级错误消息。 |
target |
string |
错误的源。 例如,如果文档无效,则为“documents”或“document id”。 |
ErrorCode
ErrorCode
值 | 说明 |
---|---|
Conflict |
表示冲突错误代码。 |
Forbidden |
表示禁止的错误代码。 |
InternalCommunicationFailed |
表示内部通信失败的错误代码。 |
InternalServerError |
表示内部服务器错误代码。 |
InvalidArgument |
表示无效的参数错误代码。 |
InvalidRequest |
表示无效的请求错误代码。 |
NotAllowed |
表示不允许的错误代码。 |
NotFound |
表示找不到的错误代码。 |
PipelineError |
表示管道错误代码。 |
ServiceUnavailable |
表示服务不可用的错误代码。 |
TooManyRequests |
表示请求错误代码过多。 |
Unauthorized |
表示未经授权的错误代码。 |
UnprocessableEntity |
表示无法处理的实体错误代码。 |
UnsupportedMediaType |
表示不支持的媒体类型错误代码。 |
InnerError
InnerError
名称 | 类型 | 说明 |
---|---|---|
code |
DetailedErrorCode |
|
details |
object |
有关错误和/或预期策略的其他支持详细信息。 |
innerError |
InnerError |
|
message |
string |
高级错误消息。 |
target |
string |
错误的源。 例如,如果文档无效,则为“documents”或“document id”。 |
Status
地位
值 | 说明 |
---|---|
Failed |
长时间运行的操作失败。 |
NotStarted |
长时间运行的操作尚未启动。 |
Running |
长时间运行的操作当前正在处理。 |
Succeeded |
长时间运行的操作已成功完成。 |
WebHook
WebHook
名称 | 类型 | 说明 |
---|---|---|
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 |
对象的显示名称。 |
events |
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 |
|
properties |
WebHookProperties |
|
self |
string (uri) |
此实体的位置。 |
status |
地位 |
|
webUrl |
string (uri) |
用于将已注册事件的 POST 请求发送到的已注册 URL。 |
WebHookEvents
WebHookEvents
名称 | 类型 | 说明 |
---|---|---|
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 |
WebHookLinks
WebHookLinks
名称 | 类型 | 说明 |
---|---|---|
ping |
string (uri) |
可用于触发将 ping 事件发送到 Web 挂钩注册的已注册 URL 的 URL 的 URL。 |
test |
string (uri) |
可用于将测试事件发送到 Web 挂钩注册的已注册 URL 的 URL。 |
WebHookProperties
WebHookProperties
名称 | 类型 | 说明 |
---|---|---|
apiVersion |
string |
在其中创建了 Web 挂钩的 API 版本。 这将定义回调中有效负载的形状。 如果不再支持有效负载类型,因为形状已更改,并且使用该形状的 API 版本被删除(弃用后),将禁用 Web 挂钩。 |
error |
EntityError |
|
secret |
string |
一个机密,用于创建有效负载的 SHA256 哈希,并将机密用作 HMAC 密钥。 调用回注册的 URL 时,此哈希将设置为 X-MicrosoftSpeechServices-Signature 标头。 |