대화형 작업이 2023년 6월 13일에 지원 중단되었습니다. 자세한 내용은 대화 작업 지원 중단을 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Package google.assistant.embedded.v1alpha1

색인

EmbeddedAssistant(인터페이스)
AudioInConfig(메시지)
AudioInConfig.Encoding(열거형)
AudioOut(메시지)
AudioOutConfig(메시지)
AudioOutConfig.Encoding(열거형)
ConverseConfig(메시지)
ConverseRequest(메시지)
ConverseResponse(메시지)
ConverseResponse.EventType(열거형)
ConverseResult(메시지)
ConverseResult.MicrophoneMode(열거형)
ConverseState(메시지)

EmbeddedAssistant

Google Assistant API를 구현하는 서비스

Converse

Converse
`rpc Converse(ConverseRequest) returns (ConverseResponse)` 삽입된 어시스턴트 서비스와 대화를 시작하거나 계속합니다. 각 호출은 1회 왕복을 수행하여 서비스에 오디오 요청을 보내고 오디오 응답을 받습니다. 오디오를 전송하는 동안 양방향 스트리밍을 사용하여 `END_OF_UTTERANCE` 이벤트와 같은 결과를 수신합니다. 대화는 하나 이상의 gRPC 연결이며, 각각 여러 스트리밍 요청 및 응답으로 구성됩니다. 예를 들어 사용자가 내 쇼핑 목록에 추가라고 말하면 어시스턴트가 무엇을 추가하고 싶으신가요?라고 응답합니다. 첫 번째 gRPC 메시지의 스트리밍된 요청 및 응답 순서는 다음과 같습니다. ConverseRequest.config ConverseRequest.audio_in ConverseRequest.audio_in ConverseRequest.audio_in ConverseRequest.audio_in ConverseResponse.event_type.END_OF_UTTERANCE ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON ConverseResponse.audio_out ConverseResponse.audio_out ConverseResponse.audio_out 사용자가 베이글이라고 말하면 어시스턴트가 네, 쇼핑 목록에 베이글을 추가했습니다라고 응답합니다. 이는 또 다른 gRPC 연결 호출로 `Converse` 메서드에 전송되며 다음과 같이 스트리밍된 요청 및 응답과 함께 다시 전송됩니다. ConverseRequest.config ConverseRequest.audio_in ConverseRequest.audio_in ConverseRequest.audio_in ConverseResponse.event_type.END_OF_UTTERANCE ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE ConverseResponse.audio_out ConverseResponse.audio_out ConverseResponse.audio_out ConverseResponse.audio_out 응답의 정확한 순서가 보장되지는 않지만, 순차적 ConverseResponse.audio_out 메시지에는 항상 오디오의 순차적 부분이 포함됩니다. 승인 다음 OAuth 범위가 필요합니다. `https://www.googleapis.com/auth/assistant-sdk-prototype` 자세한 내용은 인증 가이드를 참조하세요.

rpc Converse(ConverseRequest) returns (ConverseResponse)

삽입된 어시스턴트 서비스와 대화를 시작하거나 계속합니다. 각 호출은 1회 왕복을 수행하여 서비스에 오디오 요청을 보내고 오디오 응답을 받습니다. 오디오를 전송하는 동안 양방향 스트리밍을 사용하여 END_OF_UTTERANCE 이벤트와 같은 결과를 수신합니다.

대화는 하나 이상의 gRPC 연결이며, 각각 여러 스트리밍 요청 및 응답으로 구성됩니다. 예를 들어 사용자가 내 쇼핑 목록에 추가라고 말하면 어시스턴트가 무엇을 추가하고 싶으신가요?라고 응답합니다. 첫 번째 gRPC 메시지의 스트리밍된 요청 및 응답 순서는 다음과 같습니다.

ConverseRequest.config
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseResponse.event_type.END_OF_UTTERANCE
ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON
ConverseResponse.audio_out
ConverseResponse.audio_out
ConverseResponse.audio_out

사용자가 베이글이라고 말하면 어시스턴트가 네, 쇼핑 목록에 베이글을 추가했습니다라고 응답합니다. 이는 또 다른 gRPC 연결 호출로 Converse 메서드에 전송되며 다음과 같이 스트리밍된 요청 및 응답과 함께 다시 전송됩니다.

ConverseRequest.config
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseResponse.event_type.END_OF_UTTERANCE
ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE
ConverseResponse.audio_out
ConverseResponse.audio_out
ConverseResponse.audio_out
ConverseResponse.audio_out

응답의 정확한 순서가 보장되지는 않지만, 순차적 ConverseResponse.audio_out 메시지에는 항상 오디오의 순차적 부분이 포함됩니다.

승인

다음 OAuth 범위가 필요합니다.

https://www.googleapis.com/auth/assistant-sdk-prototype

자세한 내용은 인증 가이드를 참조하세요.

AudioInConfig

후속 요청에 제공될 audio_in 데이터를 처리하는 방법을 지정합니다. 권장 설정은 Google Assistant gRPC API 권장사항을 참고하세요.

필드

필드
`encoding`	`Encoding` 필수 모든 `audio_in` 메시지에서 전송된 오디오 데이터의 인코딩입니다.
`sample_rate_hertz`	`int32` 필수 모든 `audio_in` 메시지에서 전송된 오디오 데이터의 샘플링 레이트 (Hz)입니다. 유효한 값은 16,000~24,000이지만, 최적 값은 16,000입니다. 최상의 결과를 얻으려면 오디오 소스의 샘플링 레이트를 16,000Hz로 설정하세요. 이 설정이 불가능하다면 다시 샘플링하지 말고 오디오 소스의 기본 샘플링 레이트를 사용하면 됩니다.

encoding

Encoding

필수 모든 audio_in 메시지에서 전송된 오디오 데이터의 인코딩입니다.

sample_rate_hertz

int32

필수 모든 audio_in 메시지에서 전송된 오디오 데이터의 샘플링 레이트 (Hz)입니다. 유효한 값은 16,000~24,000이지만, 최적 값은 16,000입니다. 최상의 결과를 얻으려면 오디오 소스의 샘플링 레이트를 16,000Hz로 설정하세요. 이 설정이 불가능하다면 다시 샘플링하지 말고 오디오 소스의 기본 샘플링 레이트를 사용하면 됩니다.

인코딩

음성 메시지에서 전송된 데이터의 오디오 인코딩입니다. 오디오는 1채널 (모노)이어야 합니다. 지원되는 언어는 'en-US'입니다.

열거형
`ENCODING_UNSPECIFIED`	지정되지 않음 결과 `google.rpc.Code.INVALID_ARGUMENT`을 반환합니다.
`LINEAR16`	압축되지 않은 16비트 부호 Little Endian 샘플(리니어 PCM)입니다. 이 인코딩에는 헤더가 없고 원시 오디오 바이트만 포함됩니다.
`FLAC`	`FLAC` (무료 무손실 오디오 코덱)은 손실이 발생하지 않아 인식 성능이 저하되지 않고 필요한 대역폭이 `LINEAR16`의 약 절반에 불과하므로 권장되는 인코딩입니다. 이 인코딩에는 `FLAC` 스트림 헤더 다음에 오디오 데이터가 포함됩니다. 16비트와 24비트 샘플을 지원하지만 `STREAMINFO`의 모든 필드가 지원되지는 않습니다.

AudioOut

쿼리에 대한 어시스턴트의 응답이 포함된 오디오입니다. 오디오 데이터의 순차적인 청크가 순차적 ConverseResponse 메시지로 수신됩니다.

필드

필드
`audio_data`	`bytes` 출력 전용: 쿼리에 대한 어시스턴트의 응답이 포함된 오디오 데이터입니다. 오디오 데이터의 순차적인 청크가 순차적 `ConverseResponse` 메시지로 수신됩니다.

audio_data

bytes

출력 전용: 쿼리에 대한 어시스턴트의 응답이 포함된 오디오 데이터입니다. 오디오 데이터의 순차적인 청크가 순차적 ConverseResponse 메시지로 수신됩니다.

AudioOutConfig

서버가 audio_out 메시지를 반환할 때 사용할 원하는 서버 형식을 지정합니다.

필드

필드
`encoding`	`Encoding` 필수 모든 `audio_out` 메시지에서 반환될 오디오 데이터의 인코딩입니다.
`sample_rate_hertz`	`int32` 필수 `audio_out` 메시지에서 반환된 오디오 데이터의 샘플링 레이트(Hz)입니다. 유효한 값은 16,000~24,000입니다.
`volume_percentage`	`int32` 필수 기기 오디오 출력의 현재 볼륨 설정입니다. 유효한 값은 1~100입니다 (1~100%에 해당).

encoding

Encoding

필수 모든 audio_out 메시지에서 반환될 오디오 데이터의 인코딩입니다.

sample_rate_hertz

int32

필수 audio_out 메시지에서 반환된 오디오 데이터의 샘플링 레이트(Hz)입니다. 유효한 값은 16,000~24,000입니다.

volume_percentage

int32

필수 기기 오디오 출력의 현재 볼륨 설정입니다. 유효한 값은 1~100입니다 (1~100%에 해당).

인코딩

오디오 메시지에서 반환된 데이터의 오디오 인코딩입니다. 아래 명시된 경우를 제외하고 모든 인코딩은 헤더가 없는 원시 오디오 바이트입니다.

열거형
`ENCODING_UNSPECIFIED`	지정되지 않음 결과 `google.rpc.Code.INVALID_ARGUMENT`을 반환합니다.
`LINEAR16`	압축되지 않은 16비트 부호 Little Endian 샘플(리니어 PCM)입니다.
`MP3`	MP3 오디오 인코딩입니다. 샘플링 레이트는 페이로드에 인코딩됩니다.
`OPUS_IN_OGG`	ogg 컨테이너에 래핑된 Opus 인코딩 오디오입니다. 이렇게 하면 기본적으로 Android 및 Chrome과 같은 일부 브라우저에서 재생할 수 있는 파일이 생성됩니다. 동일한 비트 전송률을 사용하지만 인코딩 품질은 MP3보다 상당히 높습니다. 샘플링 레이트는 페이로드에 인코딩됩니다.

ConverseConfig

ConverseRequest 메시지를 처리하는 방법을 지정합니다.

필드

필드
`audio_in_config`	`AudioInConfig` 필수 후속 수신 오디오를 처리하는 방법을 지정합니다.
`audio_out_config`	`AudioOutConfig` 필수: 반환될 오디오의 형식을 지정하는 방법을 지정합니다.
`converse_state`	`ConverseState` 필수: 현재 대화상자 상태를 나타냅니다.

audio_in_config

AudioInConfig

필수 후속 수신 오디오를 처리하는 방법을 지정합니다.

audio_out_config

AudioOutConfig

필수: 반환될 오디오의 형식을 지정하는 방법을 지정합니다.

converse_state

ConverseState

필수: 현재 대화상자 상태를 나타냅니다.

ConverseRequest

클라이언트에서 보낸 최상위 메시지입니다. 클라이언트는 일반적으로 ConverseRequest 메시지를 2개 이상 보내야 합니다. 첫 번째 메시지는 config 메시지를 포함해야 하며 audio_in 데이터를 포함해서는 안 됩니다. 이후의 모든 메시지는 audio_in 데이터를 포함해야 하며 config 메시지를 포함해서는 안 됩니다.

필드

필드
통합 필드 `converse_request`. 각 `ConverseRequest`에는 이러한 필드 중 하나만 지정해야 합니다. `converse_request`은 다음 중 하나여야 합니다.
`config`	`ConverseConfig` `config` 메시지는 인식기에 요청 처리 방법을 지정하는 정보를 제공합니다. 첫 번째 `ConverseRequest` 메시지는 `config` 메시지를 포함해야 합니다.
`audio_in`	`bytes` 인식할 오디오 데이터입니다. 오디오 데이터의 순차적인 청크가 순차적 `ConverseRequest` 메시지로 전송됩니다. 첫 번째 `ConverseRequest` 메시지는 `audio_in` 데이터를 포함해서는 안 되며 이후의 모든 `ConverseRequest` 메시지는 `audio_in` 데이터를 포함해야 합니다. 오디오 바이트는 `AudioInConfig`에 지정된 대로 인코딩되어야 합니다. 오디오는 거의 실시간으로 전송되어야 합니다 (초당 16,000개의 샘플). 오디오가 훨씬 빠르거나 느리게 전송되는 경우 오류가 반환됩니다.

통합 필드 converse_request. 각 ConverseRequest에는 이러한 필드 중 하나만 지정해야 합니다. converse_request은 다음 중 하나여야 합니다.

config

ConverseConfig

config 메시지는 인식기에 요청 처리 방법을 지정하는 정보를 제공합니다. 첫 번째 ConverseRequest 메시지는 config 메시지를 포함해야 합니다.

audio_in

bytes

인식할 오디오 데이터입니다. 오디오 데이터의 순차적인 청크가 순차적 ConverseRequest 메시지로 전송됩니다. 첫 번째 ConverseRequest 메시지는 audio_in 데이터를 포함해서는 안 되며 이후의 모든 ConverseRequest 메시지는 audio_in 데이터를 포함해야 합니다. 오디오 바이트는 AudioInConfig에 지정된 대로 인코딩되어야 합니다. 오디오는 거의 실시간으로 전송되어야 합니다 (초당 16,000개의 샘플). 오디오가 훨씬 빠르거나 느리게 전송되는 경우 오류가 반환됩니다.

ConverseResponse

클라이언트가 수신한 최상위 메시지입니다. 하나 이상의 ConverseResponse 메시지가 클라이언트로 다시 스트리밍됩니다.

필드
통합 필드 `converse_response`. 이러한 필드 중 정확히 하나가 각 `ConverseResponse`에 채워집니다. `converse_response`은 다음 중 하나여야 합니다.
`error`	`Status` 출력 전용 이 옵션을 설정하면 작업의 오류를 지정하는 `google.rpc.Status` 메시지가 반환됩니다. 처리 중에 오류가 발생하면 이 메시지가 설정되고 더 이상 메시지가 전송되지 않습니다.
`event_type`	`EventType` 출력 전용: 이벤트 유형을 나타냅니다.
`audio_out`	`AudioOut` 출력 전용: 쿼리에 대한 어시스턴트의 응답이 포함된 오디오입니다.
`result`	`ConverseResult` 출력 전용 사용자의 음성 검색어에 대한 시맨틱 결과입니다.

EventType

이벤트 유형을 나타냅니다.

열거형

EVENT_TYPE_UNSPECIFIED 지정된 이벤트가 없습니다.

END_OF_UTTERANCE 이 이벤트는 서버가 사용자 발화의 끝을 감지했으며 추가 발언을 기대하지 않음을 나타냅니다. 따라서 서버는 추가 오디오를 처리하지 않습니다. 하지만 나중에 추가 결과가 반환될 수 있습니다. 클라이언트는 추가 오디오 데이터 전송을 중단하고 gRPC 연결을 반쯤 닫은 후 서버가 gRPC 연결을 닫을 때까지 추가 결과를 기다려야 합니다.

열거형
`EVENT_TYPE_UNSPECIFIED`	지정된 이벤트가 없습니다.
`END_OF_UTTERANCE`	이 이벤트는 서버가 사용자 발화의 끝을 감지했으며 추가 발언을 기대하지 않음을 나타냅니다. 따라서 서버는 추가 오디오를 처리하지 않습니다. 하지만 나중에 추가 결과가 반환될 수 있습니다. 클라이언트는 추가 오디오 데이터 전송을 중단하고 gRPC 연결을 반쯤 닫은 후 서버가 gRPC 연결을 닫을 때까지 추가 결과를 기다려야 합니다.

ConverseResult

사용자 음성 검색어에 대한 시맨틱 결과입니다.

필드
`spoken_request_text`	`string` 출력 전용 사용자가 말한 내용에 대해 인식된 스크립트입니다.
`spoken_response_text`	`string` 출력 전용 어시스턴트의 음성 응답 텍스트입니다. IFTTT 작업의 경우에만 반환됩니다.
`conversation_state`	`bytes` 출력 전용 후속 `ConverseRequest`의 상태 정보입니다. 이 값은 클라이언트에 저장되고 다음 `ConverseRequest`와 함께 `conversation_state`에 반환되어야 합니다. 클라이언트는 이 값을 해석하거나 달리 사용할 필요가 없습니다. 기기를 다시 시작할 때 이 정보를 저장할 필요가 없습니다.
`microphone_mode`	`MicrophoneMode` 출력 전용 이 `Converse` RPC가 처리된 후의 마이크 모드를 지정합니다.
`volume_percentage`	`int32` 출력 전용 볼륨 수준을 업데이트했습니다. "볼륨 높여 줘" 또는 "볼륨 4로 설정해 줘"와 같은 음성 명령이 인식되지 않는 한 이 값은 0이거나 생략 (변경되지 않음을 나타냄)합니다. 이 경우 값은 1에서 100 사이가 됩니다 (1% 에서 100%로 새롭게 확대되는 볼륨 수준에 해당). 일반적으로 클라이언트는 `audio_out` 데이터를 재생할 때 이 볼륨 수준을 사용해야 하고 이 값을 현재 볼륨 수준으로 유지하고 다음 `ConverseRequest`의 `AudioOutConfig`에 제공해야 합니다. (일부 클라이언트는 예를 들어 사용자가 돌릴 수 있는 노브를 제공하는 등 현재 볼륨 수준을 변경할 수 있는 다른 방법을 구현할 수도 있습니다.)

MicrophoneMode

Converse RPC가 완료된 후 가능한 마이크 상태입니다.

열거형
`MICROPHONE_MODE_UNSPECIFIED`	지정된 모드가 없습니다.
`CLOSE_MICROPHONE`	서비스는 사용자의 후속 질문을 기대하지 않습니다. 사용자가 마이크를 다시 활성화할 때까지 마이크가 꺼진 상태를 유지해야 합니다.
`DIALOG_FOLLOW_ON`	서비스에서 사용자의 후속 질문을 예상합니다. `AudioOut` 재생이 완료되면 (새 오디오를 전송하는 새로운 `Converse` RPC 호출을 시작하여) 마이크를 다시 열어야 합니다.

ConverseState

현재 대화상자 상태에 관한 정보를 제공합니다.

필드

필드
`conversation_state`	`bytes` 필수 이전 `ConverseResponse`에서 반환된 `conversation_state` 값입니다. 이전 `ConverseResponse`가 없는 경우 생략합니다 (필드를 설정하지 않음). 이전 `ConverseResponse`가 있는 경우 이 필드를 생략하지 마세요. 생략하면 해당 대화가 종료되고 이 새로운 요청은 새 대화를 시작합니다.

conversation_state

bytes

필수 이전 ConverseResponse에서 반환된 conversation_state 값입니다. 이전 ConverseResponse가 없는 경우 생략합니다 (필드를 설정하지 않음). 이전 ConverseResponse가 있는 경우 이 필드를 생략하지 마세요. 생략하면 해당 대화가 종료되고 이 새로운 요청은 새 대화를 시작합니다.