call: recordResponse

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

発信者からの短い音声応答を録音します。

ボットは、この API を使用して、応答を求められた後に呼び出し元からの音声応答をキャプチャできます。

操作の処理方法の詳細については、「 commsOperation」を参照してください。

メモ：この API は、serviceHostedMediaConfig で開始される呼び出しでのみサポートされます。

このアクションは、呼び出し全体を記録するためのものではありません。 記録の最大長は 2 分です。Cloud Communications Platform は記録を永続的に保存せず、通話が終了した直後に破棄されます。 ボットは、完了した通知で指定された recordingLocation 値を使用して、記録操作が完了した後、すぐに記録をダウンロードする必要があります。

メモ： アプリケーションがアクセスする通話や会議、またはそのメディア コンテンツから派生したデータからメディア コンテンツを記録したり保存したりすることはできません。 お客様が、通信のデータ保護と機密性に関する地域の法律および規制に準拠していることを確認してください。 詳細については、 利用規約 を参照し、法律顧問に相談してください。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ❌ ❌ ❌

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) サポートされていません。 サポートされていません。
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション Calls.AccessMedia.All 注意事項なし。

HTTP 要求

POST /app/calls/{id}/recordResponse
POST /communications/calls/{id}/recordResponse

注:/app パスは廃止されます。 今後は、/communications パスを使用してください。

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。
Content-type application/json. 必須です。

要求本文

要求本文で、次のパラメーターを含む JSON オブジェクトを指定します。

パラメーター 型 説明
プロンプト MediaPrompt コレクション 再生するプロンプト。 サポートされる mediaPrompt コレクションの最大サイズは 1 です。
bargeInAllowed ブール型 true の場合、recordResponse 要求は、他の既存のキューに登録されたレコード/現在処理されているレコード/playprompt 要求に割り込まれます。 既定値 = false。
initialSilenceTimeoutInSeconds Int32 レコード応答操作を開始してからタイムアウトして操作を失敗させた時点から許可される最大初期無音 (ユーザーの無音)。 プロンプトを再生している場合は、プロンプトの完了後にこのタイマーが開始されます。 既定値 = 5 秒、最小 = 1 秒、最大 = 120 秒
maxSilenceTimeoutInSeconds Int32 ユーザーが話し始めた後に許可される最大無音 (一時停止) 時間。 既定値 = 5 秒、最小 = 1 秒、最大 = 120 秒。
maxRecordDurationInSeconds Int32 記録を停止する前の recordResponse 操作の最大期間。 既定値 = 5 秒、最小 = 1 秒、最大 = 120 秒。
playBeep ブール型 true の場合は、メッセージの記録を開始できることをユーザーに示すビープ音を再生します。 既定値 = true。
stopTones String collection 録音を終了するように指定されたトーンを停止します。
clientContext String 一意のクライアント コンテキスト文字列。 最大制限は 256 文字です。

メモ： 最大記録時間は、5 分から 2 分に短縮されました。

応答

このメソッドは、 200 OK HTTP 応答コードと URI を持つ Location ヘッダーを、この要求用に作成された recordOperation に返します。

例

次の例は、この API を呼び出す方法を示しています。

例 1: 呼び出し元からの短い音声応答を記録する

要求

次の例は要求を示しています。

POST https://graph.microsoft.com/beta/communications/calls/{id}/recordResponse
Content-Type: application/json
Content-Length: 394

{
  "bargeInAllowed": true,
  "clientContext": "d45324c1-fcb5-430a-902c-f20af696537c",
  "prompts": [
    {
      "@odata.type": "#microsoft.graph.mediaPrompt",
      "mediaInfo": {
        "uri": "https://cdn.contoso.com/beep.wav",
        "resourceId": "1D6DE2D4-CD51-4309-8DAA-70768651088E"
      }
    }
  ],
  "maxRecordDurationInSeconds": 10,
  "initialSilenceTimeoutInSeconds": 5,
  "maxSilenceTimeoutInSeconds": 2,
  "playBeep": true,
  "stopTones": [ "#", "1", "*" ]
}
応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Location: https://graph.microsoft.com/beta/communications/calls/57dab8b1-894c-409a-b240-bd8beae78896/operations/0fe0623f-d628-42ed-b4bd-8ac290072cc5

{
  "@odata.type": "#microsoft.graph.recordOperation",
  "id": "0fe0623f-d628-42ed-b4bd-8ac290072cc5",
  "status": "running",
  "completionReason": null,
  "resultInfo": null,
  "recordingLocation": null,
  "clientContext": "d45324c1-fcb5-430a-902c-f20af696537c"
}
通知 - 操作が完了しました
POST https://bot.contoso.com/api/calls
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.commsNotifications",
  "value": [
    {
      "@odata.type": "#microsoft.graph.commsNotification",
      "changeType": "deleted",
      "resourceUrl": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896/operations/0FE0623FD62842EDB4BD8AC290072CC5",
      "resourceData": {
        "@odata.type": "#microsoft.graph.recordOperation",
        "@odata.id": "/communications/calls/57DAB8B1894C409AB240BD8BEAE78896/operations/0FE0623FD62842EDB4BD8AC290072CC5",
        "@odata.etag": "W/\"54451\"",
        "id": "0fe0623f-d628-42ed-b4bd-8ac290072cc5",
        "clientContext": "d45324c1-fcb5-430a-902c-f20af696537c",
        "status": "completed",
        "recordingLocation": "https://file.location/17e3b46c-f61d-4f4d-9635-c626ef18e6ad",
        "recordingAccessToken": "<access-token>",
        "completionReason": "stopToneDetected"
      }
    }
  ]
}

例 2: 記録ファイルの取得

メモ： アプリケーションがアクセスする通話や会議、またはそのメディア コンテンツから派生したデータからメディア コンテンツを記録したり、保持したりすることはできません。 お客様が、通信のデータ保護と機密性に関する地域の法律および規制に準拠していることを確認してください。 詳細については、 利用規約 を参照し、法律顧問に相談してください。

要求
GET https://file.location/17e3b46c-f61d-4f4d-9635-c626ef18e6ad
Authorization: Bearer <recordingAccessToken>
応答
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Date: Thu, 17 Jan 2019 01:46:37 GMT
Content-Type: application/octet-stream

(application/octet-stream of size 160696 bytes)

メモ： アプリケーションがアクセスする通話や会議、またはそのメディア コンテンツから派生したデータからメディア コンテンツを記録したり、保持したりすることはできません。 お客様が、通信のデータ保護と機密性に関する地域の法律および規制に準拠していることを確認してください。 詳細については、 利用規約 を参照し、法律顧問に相談してください。