通話: レコードcall: record

重要

Microsoft Graph の/betaバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。Use of these APIs in production applications is not supported.

通話から短いオーディオクリップを録音します。Record a short audio clip from the call. これは、ボットがプロンプトに従って発信者からの音声応答を取得したい場合に便利です。This is useful if the bot wants to capture a voice response from the caller following a prompt.

注意

Record アクションは、 serviceHostedMediaConfigを使用して開始された通話に対してのみサポートされます。The record action is supported only for calls that are initiated with serviceHostedMediaConfig. この操作では、呼び出し全体が記録されることはありません。This action does not record the entire call. 録音の最大長は5分です。The maximum length of the recording is 5 minutes. レコーディングは、クラウドコミュニケーションプラットフォームによって permamently には保存されず、通話が終了した直後に破棄されます。The recording is not saved permamently by the Cloud Communications Platform and is discarded shortly after the call ends. Bot は、録音操作が終了した後で、(完了した通知で指定されたrecordingLocation値を使用して) すぐにレコーディングをダウンロードする必要があります。The bot must download the recording promptly (using the recordingLocation value given in the completed notification) after the recording operation finishes.

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) サポート対象外Not Supported
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) サポート対象外Not Supported
アプリケーションApplication Calls.AccessMedia.AllCalls.AccessMedia.All

HTTP 要求HTTP request

POST /app/calls/{id}/record

要求ヘッダーRequest headers

名前Name 説明Description
AuthorizationAuthorization ベアラー {トークン}。必須。Bearer {token}. Required.

要求本文Request body

要求本文で、次のパラメーターを含む JSON オブジェクトを指定します。In the request body, provide a JSON object with the following parameters.

パラメーターParameter Type 説明Description
促しprompts MediapromptコレクションmediaPrompt collection レコーディングの開始前に再生するプロンプトのコレクション (ある場合)。Collection of prompts to play (if any) before recording starts. ユーザーは、"playPrompt" アクションを個別に指定するか、"record" の一部として指定することができます。ほとんどすべてのレコードはプロンプトで preceeded れます。Customers can choose to specify "playPrompt" action separately or specify as part of "record" - mostly all records are preceeded by a prompt. Current support は、コレクションの一部として1つのプロンプトのみを対象としています。Current support is only for a single prompt as part of the collection.
bargeInAllowedbargeInAllowed BooleanBoolean True の場合、このレコードの要求は、キューに登録されている他の既存のレコード/再生プロンプト要求になります。If true, this record request will barge into other existing queued-up/currently-processing record/playprompt requests. 既定値は false です。Default = false.
initialSilenceTimeoutInSecondsinitialSilenceTimeoutInSeconds Int32Int32 操作を開始する前にレコード操作を開始するときに許容される最大初期無音時間 (ユーザー無音)。Maximum initial silence (user silence) allowed from the time we start the record operation before we timeout and fail the operation. プロンプトを再生している場合は、プロンプトが終了した後、このタイマーが開始されます。If we are playing a prompt, then this timer starts after prompt finishes. 既定値 = 5 秒、最小値 = 1 秒、最大 = 300 秒Default = 5 seconds, Min = 1 second, Max = 300 seconds
maxSilenceTimeoutInSecondsmaxSilenceTimeoutInSeconds Int32Int32 ユーザーが話し始めた後に許可される最大無音時間 (一時停止時間)。Maximum silence (pause) time allowed after a user has started speaking. 既定値は5秒、最小値は1秒、最大値は300秒です。Default = 5 seconds, Min = 1 second, Max = 300 seconds.
maxRecordDurationInSecondsmaxRecordDurationInSeconds Int32Int32 レコーディングを停止する前のレコード操作の最大期間。Max duration for a record operation before stopping recording. 既定値は5秒、最小値は1秒、最大値は300秒です。Default = 5 seconds, Min = 1 second, Max = 300 seconds.
再生のビープ音playBeep BooleanBoolean True の場合は、ユーザーにメッセージの録音を開始できることを示す警告音を鳴らします。If true, plays a beep to indicate to the user that they can start recording their message. 既定値は true です。Default = true.
stopTonesstopTones 文字列コレクションString collection 録音を終了するために指定されたトーンを停止します。Stop tones specified to end recording.
clientContextclientContext StringString 一意のクライアントコンテキスト文字列。Unique Client Context string. 最大256文字を使用できます。Can have a maximum of 256 characters.

応答Response

このメソッドは、 200 OK応答コードと、この要求に対して作成されたRECORDOPERATIONへの URI を持つ Location ヘッダーを返します。This method returns a 200 OK response code and a Location header with a URI to the recordOperation created for this request.

Example

次の例は、この API を呼び出す方法を示しています。The following example shows how to call this API.

要求Request

次の例は要求を示しています。The following example shows the request.

POST https://graph.microsoft.com/beta/app/calls/{id}/record
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", "*" ]
}
応答Response

次の例は応答を示しています。The following example shows the response.

注: 読みやすくするために、ここに示す応答オブジェクトは短くされている場合があります。実際の呼び出しからは、すべてのプロパティが返されます。Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.type": "#microsoft.graph.recordOperation",
  "status": "running",
  "createdDateTime": "2018-09-06T15:58:41Z",
  "lastActionDateTime": "2018-09-06T15:58:41Z",
  "completionReason": null,
  "resultInfo": null,
  "recordingLocation": null,
  "clientContext": "d45324c1-fcb5-430a-902c-f20af696537c"
}

通知-操作が完了しましたNotification - operation completed
POST https://bot.contoso.com/api/calls
Authorization: Bearer <TOKEN>
Content-Type: application/json
{
  "value": [
    {
      "changeType": "deleted",
      "resource": "/app/calls/57DAB8B1894C409AB240BD8BEAE78896/operations/0FE0623FD62842EDB4BD8AC290072CC5",
      "resourceData": {
        "@odata.type": "#microsoft.graph.recordOperation",
        "@odata.id": "/app/calls/57DAB8B1894C409AB240BD8BEAE78896/operations/0FE0623FD62842EDB4BD8AC290072CC5",
        "@odata.etag": "W/\"54451\"",
        "clientContext": "d45324c1-fcb5-430a-902c-f20af696537c",
        "status": "completed",
        "recordingLocation": "https://file.location/17e3b46c-f61d-4f4d-9635-c626ef18e6ad",
        "recordingAccessToken": "<access-token>",
        "completionReason": "stopToneDetected"
      }
    }
  ]
}
レコーディングファイルの取得-要求Get recording file - Request

次の例は、レコーディングの内容を取得する要求を示しています。The following example shows the request to get the content of the recording.

GET https://file.location/17e3b46c-f61d-4f4d-9635-c626ef18e6ad
Authorization: Bearer <recordingAccessToken>
レコーディングファイル応答の取得Get recording file - Response

以下は、応答の例です。Here is an example of the response.

GET https://file.location/17e3b46c-f61d-4f4d-9635-c626ef18e6ad
Transfer-Encoding: chunked
Date: Thu, 17 Jan 2019 01:46:37 GMT
Content-Type: application/octet-stream

(application/octet-stream of size 160696 bytes)