你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

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

WebHookEvents

webUrl True

string (uri)

用于将已注册事件的 POST 请求发送到的已注册 URL。

customProperties

object

此实体的自定义属性。 允许的最大密钥长度为 64 个字符,允许的最大值长度为 256 个字符,允许的条目计数为 10。

description

string

对象的说明。

links

WebHookLinks

WebHookLinks

properties

WebHookProperties

WebHookProperties

响应

名称 类型 说明
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 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"
}

定义

名称 说明
DetailedErrorCode

DetailedErrorCode

EntityError

EntityError

Error

错误

ErrorCode

ErrorCode

InnerError

InnerError

Status

地位

WebHook

WebHook

WebHookEvents

WebHookEvents

WebHookLinks

WebHookLinks

WebHookProperties

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

ErrorCode
高级错误代码。

details

Error[]

有关错误和/或预期策略的其他支持详细信息。

innerError

InnerError

InnerError
符合认知服务 API 准则的新内部错误格式,可在 https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow获取。 这包括必需的属性 ErrorCode、消息和可选属性目标、详细信息(键值对)、内部错误(可嵌套)。

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

DetailedErrorCode
详细的错误代码枚举。

details

object

有关错误和/或预期策略的其他支持详细信息。

innerError

InnerError

InnerError
符合认知服务 API 准则的新内部错误格式,可在 https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow获取。 这包括必需的属性 ErrorCode、消息和可选属性目标、详细信息(键值对)、内部错误(可嵌套)。

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

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

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

名称 类型 说明
ping

string (uri)

可用于触发将 ping 事件发送到 Web 挂钩注册的已注册 URL 的 URL 的 URL。

test

string (uri)

可用于将测试事件发送到 Web 挂钩注册的已注册 URL 的 URL。

WebHookProperties

WebHookProperties

名称 类型 说明
apiVersion

string

在其中创建了 Web 挂钩的 API 版本。 这将定义回调中有效负载的形状。 如果不再支持有效负载类型,因为形状已更改,并且使用该形状的 API 版本被删除(弃用后),将禁用 Web 挂钩。

error

EntityError

EntityError

secret

string

一个机密,用于创建有效负载的 SHA256 哈希,并将机密用作 HMAC 密钥。 调用回注册的 URL 时,此哈希将设置为 X-MicrosoftSpeechServices-Signature 标头。