PlayAudioAndGetDigits

播放音频并收集 DTMF 数字。如果发生失败，例如用户未输入正确的 DTMF 数字，该操作将播放“失败”音频，然后重播主音频，直到 SIP 媒体应用程序耗尽 Repeat 参数中定义的尝试次数。

您必须播放 S3 存储桶中的音频文件。S3 存储桶必须与 SIP 媒体应用程序处于同一 AWS 账户。此外，您必须向 Amazon Chime SDK 语音连接器服务主体授予 s3:GetObject 的访问权限 (voiceconnector.chime.amazonaws.com)。您可以使用 S3 控制台或 CLI 完成该操作。

以下代码示例显示典型的 S3 存储桶策略。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SMARead",
            "Effect": "Allow",
            "Principal": {
                "Service": "voiceconnector.chime.amazonaws.com"
            },
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::bucket-name/*",
                "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "aws-account-id"
                }
            }
        }
    ]
}

音频服务代表您的 Sip 媒体应用程序对 S3 存储桶进行读写操作。为避免混淆代理问题，您可以将 S3 存储桶的访问限制为单个 SIP 媒体应用程序。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SMARead",
            "Effect": "Allow",
            "Principal": {
                "Service": "voiceconnector.chime.amazonaws.com"
            },
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::bucket-name/*",
                "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "aws-account-id",
                    "aws:SourceArn": "arn:aws:chime:region:aws-account-id:sma/sip-media-application-id"
                }
            }
        }
    ]
}

以下示例显示典型的 PlayAudioAndGetDigits 操作。

{
    "Type" : "PlayAudioAndGetDigits",
    "Parameters" : {
        "CallId": "call-id-1",
        "ParticipantTag": "LEG-A"      
        "InputDigitsRegex": "^\d{2}#$",
        "AudioSource": {
            "Type": "S3",
            "BucketName": "bucket-name",
            "Key": "audio-file-1.wav"
        },
        "FailureAudioSource": {
            "Type": "S3",
            "BucketName": "bucket-name",
            "Key": "audio-file-failure.wav"
        },
        "MinNumberOfDigits": 3,
        "MaxNumberOfDigits": 5,
        "TerminatorDigits": ["#"],        
        "InBetweenDigitsDurationInMilliseconds": 5000,
        "Repeat": 3,
        "RepeatDurationInMilliseconds": 10000
    }
}

CallId

描述 — AWS Lambda 函数调用的 CallDetails 中参与者的 CallId

允许的值 — 有效的调用 ID

必填 — 否

默认值 – 无

ParticipantTag

描述 — CallDetails 中一个已连接参与者的 ParticipantTag

允许的值 — LEG-A 或 LEG-B

必填 — 否

默认值 — 已调用 callLeg 的 ParticipantTag，如指定 CallId，则忽略该值

InputDigitsRegex

描述 — 正则表达式模式

允许的值 — 有效的正则表达式模式

必填 — 否

默认值 – 无

AudioSource.Type

描述 — 音频文件来源的类型

允许的值 — 一个 S3 存储桶

必填 — 是

默认值 — "S3"

AudioSource.BucketName

描述 — 对于 S3 AudioSource.Type 值，S3 存储桶必须属于 SIP 应用程序所在的 AWS 账户。S3 存储桶必须有权访问 Amazon Chime SDK 语音连接器服务主体 (voiceconnector.chime.amazonaws.com)。

允许的值 — Amazon Chime SDK 具有 s3:GetObject 操作权限的有效 S3 存储桶。

必填 — 是

默认值 – 无

AudioSource.Key

描述 — AudioSource.BucketName S3 存储桶中音频对象的密钥名称。

允许的值 — 有效的音频文件

必填 — 是

默认值 – 无

FailureAudioSource.Type

描述 — FailureAudioSource.BucketName S3 存储桶中音频对象的密钥名称。

允许的值 — S3

必填 — 是

默认值 – 无

FailureAudioSource.BucketName

描述 — 对于 S3 来源类型，S3 存储桶必须属于 SIP 应用程序所在的 AWS 账户。Amazon Chime SDK 语音连接器服务主体 (voiceconnector.chime.amazonaws.com) 必须有权访问 S3 存储桶。

允许的值 — Amazon Chime SDK 具有 s3:GetObject 操作权限的有效 S3 存储桶。

必填 — 是

默认值 – 无

FailureAudioSource.Key

描述 — FailureAudioSource.BucketName S3 存储桶中音频对象的密钥名称。

允许的值 — 有效的音频文件

必填 — 是

默认值 – 无

MinNumberOfDigits

描述 — 在超时或播放“调用失败”音频之前捕获的最小数字位数。

允许的值 — >=0

必填 — 否

默认值 — 0

MaxNumberOfDigits

描述 — 在没有终止数字的情况下停止前要捕获的最大数字位数。

允许的值 — >MinNumberOfDigits

必填 — 否

默认值 — 128

TerminatorDigits

描述 — 当用户输入的数字小于 MaxNumberOfDigits 时，用于结束输入的数字

允许的值 — 以下数字中的任意一个：0123456789#*

必填 — 否

默认值 — #

InBetweenDigitsDurationInMilliseconds

描述 — 播放 FailureAudio 之前数字输入之间的等待时间（以毫秒为单位）。

允许的值 — >0

必填 — 否

默认值 — 如未指定，默认为 RepeatDurationInMilliseconds 值

Repeat

描述 — 尝试获取数字的总次数。

允许的值 — >0

必填 — 否

默认值 — 1

RepeatDurationInMilliseconds

描述 — Repeat 尝试之间的等待时间（以毫秒为单位）

允许的值 — >0

必填 — 是

默认值 – 无

SIP 媒体应用程序始终在运行 PlayAudioAndGetDigits 操作后调用其 AWS Lambda 功能，事件类型为 ACTION_SUCCESSFUL 或 ACTION_FAILED 调用。当应用程序成功收集数字时，它会在 ActionData 对象中设置 ReceivedDigits 值。以下示例显示 AWS Lambda 函数的调用事件结构。

{
    "SchemaVersion": "1.0",
    "Sequence": 3,
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData": {
        "Type": "PlayAudioAndGetDigits",
        "Parameters" : {
            "CallId": "call-id-1",
            "ParticipantTag": "LEG-A",
            "InputDigitsRegex": "^\d{2}#$",
            "AudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-1.wav"
            },
            "FailureAudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-failure.wav"
            },
            "MinNumberOfDigits": 3,
            "MaxNumberOfDigits": 5,
            "TerminatorDigits": ["#"],
            "InBetweenDigitsDurationInMilliseconds": 5000,
            "Repeat": 3,
            "RepeatDurationInMilliseconds": 10000
        },
        "ErrorType": "InvalidAudioSource",
        "ErrorMessage": "Audio Source parameter value is invalid."
    },
        "ReceivedDigits": "1234"
    },
    "CallDetails": {
        ...
    }
}

错误处理

发生验证错误时，SIP 媒体应用程序会调用 AWS Lambda 函数并显示相应的错误消息。下表列出可能的错误消息。

错误	消息	Reason
InvalidAudioSource	音频来源参数值无效。	出现此错误可能基于多种原因。例如，由于权限问题或 S3 存储桶问题，SIP 媒体应用程序无法访问文件。或者，由于持续时间、大小或不受支持的格式等原因，音频文件可能无法通过验证。
InvalidActionParameter	操作的 CallId 或 ParticipantTag 参数无效。	CallId、ParticipantTag 或其他参数无效。
SystemException	运行操作时出现系统错误。	运行操作时出现一个系统错误。

当操作由于超时或重试次数过多而无法收集指定数字位数时，SIP 媒体应用程序将使用 ACTION_FAILED 调用事件类型调用 AWS Lambda 函数。

{
    "SchemaVersion": "1.0",
    "Sequence": 4,
    "InvocationEventType": "ACTION_FAILED",
    "ActionData": {
        "Type": "PlayAudioAndGetDigits",
        "Parameters" : {
            "CallId": "call-id-1",
            "ParticipantTag": "LEG-A",
            "InputDigitsRegex": "^\d{2}#$",
            "AudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-1.wav"
            },
            "FailureAudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-failure.wav"
            },
            "MinNumberOfDigits": 3,
            "MaxNumberOfDigits": 5,
            "TerminatorDigits": ["#"],
            "InBetweenDigitsDurationInMilliseconds": 5000,
            "Repeat": 3,
            "RepeatDurationInMilliseconds": 10000
        },
        "ErrorType": "InvalidAudioSource",
        "ErrorMessage": "Audio Source parameter value is invalid."
    }
    "CallDetails": {
        ...
    }
}

在 GitHub 上查看工作示例：

• https://github.com/aws-samples/amazon-chime-sma-bridging.

• https://github.com/aws-samples/amazon-chime-sma-update-call