Web Hooks - Create

リファレンス

Service:: Azure AI Services

API Version:: v3.2-preview.2

新しい Web フックを作成します。
構成にプロパティシークレットが存在し、空でない文字列が含まれている場合は、シークレットを HMAC キーとして使用してペイロードの SHA256 ハッシュを作成するために使用されます。このハッシュは、登録済みの URL に再度呼び出すときに X-MicrosoftSpeechServices-Signature ヘッダーとして設定されます。

登録済み URL を呼び出すとき、要求には、登録されたイベントの種類のいずれかを含む X-MicrosoftSpeechServices-Event ヘッダーが含まれます。登録されたイベントの種類ごとに 1 つの要求があります。

Web フックを正常に登録した後は、チャレンジ/応答が完了するまで使用できません。これを行うには、validationToken というクエリパラメーターを使用して、イベントの種類のチャレンジを含む要求が行われます。応答本文として validationToken クエリパラメーターの値を含む 200 OK でチャレンジに応答します。チャレンジ/応答が正常に完了すると、Web フックはイベントの受信を開始します。

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

URI パラメーター

名前	/	必須	型	説明
endpoint	path	True	string	サポートされている Cognitive Services エンドポイント (プロトコルとホスト名など)。 https://westus.api.cognitive.microsoft.com

要求本文

名前	必須	型	説明
displayName	True	string	オブジェクトの表示名。
events	True	WebHookEvents	WebHookEvents
webUrl	True	string	登録されたイベントの POST 要求の送信先として使用される登録済み URL。
customProperties		object	このエンティティのカスタムプロパティ。許可されるキーの最大長は 64 文字、最大許容値の長さは 256 文字、許可されるエントリの数は 10 です。
description		string	オブジェクトの説明。
properties		WebHookProperties	WebHookProperties

応答

名前	型	説明
201 Created	WebHook	応答には、ペイロードとしてのエンティティに関する情報と、ヘッダーとしての場所が含まれます。 Headers Location: string
Other Status Codes	Error	エラーが発生しました。

名前

型

説明

201 Created

WebHook

応答には、ペイロードとしてのエンティティに関する情報と、ヘッダーとしての場所が含まれます。

Headers

Location: string

Other Status Codes

Error

エラーが発生しました。

セキュリティ

Ocp-Apim-Subscription-Key

コグニティブサービスアカウントキーをここで指定します。

Type: apiKey
In: header

Authorization

このリージョンの STS によって返される JWT からアクセストークンを指定します。 STS URL に次のクエリ文字列を追加して、トークンに管理スコープを追加してください: ?scope=speechservicesmanagement

Type: apiKey
In: header

例

Create a web hook

Sample Request

HTTP

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."
}

Sample Response

Status code:: 201

Location: https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d

Response Body

{
  "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"
}

定義

名前	説明
DetailedErrorCode	DetailedErrorCode
EntityError	EntityError
Error	エラー
ErrorCode	ErrorCode
InnerError	InnerError
Status	Status
WebHook	WebHook
WebHookEvents	WebHookEvents
WebHookLinks	WebHookLinks
WebHookProperties	WebHookProperties

DetailedErrorCode

名前	型	説明
DataImportFailed	string	データのインポートに失敗しました。
DeleteNotAllowed	string	削除は許可されません。
DeployNotAllowed	string	デプロイは許可されていません。
DeployingFailedModel	string	失敗したモデルのデプロイ。
EmptyRequest	string	空の要求。
EndpointCannotBeDefault	string	エンドポイントを既定にすることはできません。
EndpointNotUpdatable	string	エンドポイントは更新できません。
EndpointWithoutLogging	string	ログのないエンドポイント。
ExceededNumberOfRecordingsUris	string	記録 URI の数を超えました。
FailedDataset	string	失敗したデータセット。
Forbidden	string	Forbidden.
InUseViolation	string	使用中の違反。
InaccessibleCustomerStorage	string	アクセスできない顧客ストレージ。
InvalidAdaptationMapping	string	無効な適応マッピング。
InvalidBaseModel	string	ベースモデルが無効です。
InvalidCallbackUri	string	コールバック URI が無効です。
InvalidCollection	string	コレクションが無効です。
InvalidDataset	string	データセットが無効です。
InvalidDocument	string	ドキュメントが無効です。
InvalidDocumentBatch	string	ドキュメントバッチが無効です。
InvalidLocale	string	ロケールが無効です。
InvalidLogDate	string	ログの日付が無効です。
InvalidLogEndTime	string	ログの終了時刻が無効です。
InvalidLogId	string	ログ ID が無効です。
InvalidLogStartTime	string	ログの開始時刻が無効です。
InvalidModel	string	モデルが無効です。
InvalidModelUri	string	モデル URI が無効です。
InvalidParameter	string	無効なパラメーター。
InvalidParameterValue	string	パラメーターの値が無効です。
InvalidPayload	string	ペイロードが無効です。
InvalidPermissions	string	アクセス許可が無効です。
InvalidPrerequisite	string	前提条件が無効です。
InvalidProductId	string	製品 ID が無効です。
InvalidProject	string	プロジェクトが無効です。
InvalidProjectKind	string	プロジェクトの種類が無効です。
InvalidRecordingsUri	string	無効な記録 URI。
InvalidRequestBodyFormat	string	要求本文の形式が無効です。
InvalidSasValidityDuration	string	sas の有効期間が無効です。
InvalidSkipTokenForLogs	string	ログのスキップトークンが無効です。
InvalidSourceAzureResourceId	string	ソース Azure リソース ID が無効です。
InvalidSubscription	string	サブスクリプションが無効です。
InvalidTest	string	テストが無効です。
InvalidTimeToLive	string	有効期間が無効です。
InvalidTopForLogs	string	ログの top が無効です。
InvalidTranscription	string	文字起こしが無効です。
InvalidWebHookEventKind	string	Web フックイベントの種類が無効です。
MissingInputRecords	string	入力レコードがありません。
ModelCopyOperationExists	string	モデルのコピー操作が存在します。
ModelDeploymentNotCompleteState	string	モデルのデプロイが完了していない状態です。
ModelDeprecated	string	モデルは非推奨になりました。
ModelExists	string	モデルが存在します。
ModelMismatch	string	モデルの不一致。
ModelNotDeployable	string	モデルはデプロイできません。
ModelVersionIncorrect	string	モデルのバージョンが正しくありません。
NoUtf8WithBom	string	bom を含む utf8 はありません。
OnlyOneOfUrlsOrContainerOrDataset	string	URL またはコンテナーまたはデータセットの 1 つだけ。
ProjectGenderMismatch	string	プロジェクトの性別の不一致。
QuotaViolation	string	クォータ違反。
SingleDefaultEndpoint	string	単一の既定のエンドポイント。
SkuLimitsExist	string	SKU の制限が存在します。
SubscriptionNotFound	string	サブスクリプションが見つかりません。
UnexpectedError	string	予期しないエラー。
UnsupportedClassBasedAdaptation	string	サポートされていないクラスベースの適応。
UnsupportedDelta	string	サポートされていないデルタ。
UnsupportedDynamicConfiguration	string	サポートされていない動的構成。
UnsupportedFilter	string	サポートされていないフィルター。
UnsupportedLanguageCode	string	サポートされていない言語コード。
UnsupportedOrderBy	string	サポートされていない順序。
UnsupportedPagination	string	サポートされていない改ページ位置。
UnsupportedTimeRange	string	サポートされていない時間範囲。

EntityError

名前	型	説明
code	string	このエラーのコード。
message	string	このエラーのメッセージ。

Error

エラー

名前	型	説明
code	ErrorCode	ErrorCode 高レベルのエラーコード。
details	Error[]	エラーや予想されるポリシーに関する追加のサポートの詳細。
innerError	InnerError	InnerError で使用できる https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8owCognitive Services API ガイドラインに準拠した新しい内部エラー形式。必須プロパティとして ErrorCode、message、省略可能プロパティとして target、details (キーと値のペア)、inner error (入れ子が可能) が含まれています。
message	string	高レベルのエラーメッセージ。
target	string	エラーのソースです。たとえば、無効なドキュメントの場合は "documents" または "document id" になります。

ErrorCode

名前	型	説明
Conflict	string	競合エラーコードを表します。
Forbidden	string	禁止されているエラーコードを表します。
InternalCommunicationFailed	string	内部通信に失敗したエラーコードを表す。
InternalServerError	string	内部サーバーエラーコードを表します。
InvalidArgument	string	無効な引数エラーコードを表しています。
InvalidRequest	string	無効な要求エラーコードを表します。
NotAllowed	string	許可されていないエラーコードを表します。
NotFound	string	見つからないエラーコードを表します。
PipelineError	string	パイプラインエラーのエラーコードを表します。
ServiceUnavailable	string	サービスを使用できないエラーコードを表します。
TooManyRequests	string	要求の数が多すぎるエラーコードを表しています。
Unauthorized	string	承認されていないエラーコードを表します。
UnprocessableEntity	string	処理不可能なエンティティエラーコードを表します。
UnsupportedMediaType	string	サポートされていないメディアの種類のエラーコードを表します。

InnerError

名前	型	説明
code	DetailedErrorCode	DetailedErrorCode 詳細なエラーコード列挙型。
details	object	エラーや予想されるポリシーに関する追加のサポートの詳細。
innerError	InnerError	InnerError で使用できる https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8owCognitive Services API ガイドラインに準拠した新しい内部エラー形式。必須プロパティとして ErrorCode、message、省略可能プロパティとして target、details (キーと値のペア)、inner error (入れ子が可能) が含まれています。
message	string	高レベルのエラーメッセージ。
target	string	エラーのソースです。たとえば、無効なドキュメントの場合は "documents" または "document id" になります。

Status

名前	型	説明
Failed	string	実行時間の長い操作が失敗しました。
NotStarted	string	実行時間の長い操作はまだ開始されていません。
Running	string	実行時間の長い操作は現在処理中です。
Succeeded	string	実行時間の長い操作が正常に完了しました。

WebHook

名前	型	説明
createdDateTime	string	オブジェクトが作成されたときのタイムスタンプ。タイムスタンプは 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	現在の状態が入力されたときのタイムスタンプ。タイムスタンプは 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	このエンティティの場所。
status	Status	Status API の現在の状態について説明する
webUrl	string	登録されたイベントの POST 要求の送信先として使用される登録済み URL。

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	Web フック登録の登録済み URL への ping イベントの送信をトリガーするために使用できる URL。詳細については、操作 "WebHooks_Ping" を参照してください。
test	string	Web フック登録の登録済み URL にテストイベントを送信するために使用できる URL。詳細については、操作 "WebHooks_Test" を参照してください。

WebHookProperties

名前	型	説明
apiVersion	string	Web フックが作成された API バージョン。これにより、コールバック内のペイロードの形状が定義されます。ペイロードの種類がサポートされなくなった場合は、図形が変更され、それを使用する API バージョンが削除されるため (非推奨の後)、Web フックは無効になります。
error	EntityError	EntityError
secret	string	シークレットを HMAC キーとして使用してペイロードの SHA256 ハッシュを作成するために使用されるシークレット。このハッシュは、登録された URL に呼び出すときに X-MicrosoftSpeechServices-Signature ヘッダーとして設定されます。

次の方法で共有

Web Hooks - Create

URI パラメーター

要求本文

応答

セキュリティ

Ocp-Apim-Subscription-Key

Authorization

例

Create a web hook

Sample Request

Sample Response

定義

DetailedErrorCode

EntityError

Error

ErrorCode

InnerError

Status

WebHook

WebHookEvents

WebHookLinks

WebHookProperties

その他のリソース