Package google.assistant.embedded.v1alpha2

색인

EmbeddedAssistant

Google Assistant API를 구현하는 서비스입니다.

어시스트

rpc Assist(AssistRequest) returns (AssistResponse)

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

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

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript '내 쇼핑 목록에 추가'
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

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

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.dialog_state_out.microphone_mode.CLOSE_MICROPHONE
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

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

승인 범위

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

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

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

AssistConfig

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

필드
audio_out_config

AudioOutConfig

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

screen_out_config

ScreenOutConfig

선택사항 서버가 시각적 화면 응답을 반환할 때 사용할 형식을 지정합니다.

dialog_state_in

DialogStateIn

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

device_config

DeviceConfig

특정 기기를 고유하게 식별하는 기기 설정입니다.

debug_config

DebugConfig

선택사항 전체 Assist RPC의 디버깅 매개변수입니다.

통합 필드 type.

type는 다음 중 하나여야 합니다.
audio_in_config

AudioInConfig

이후 수신 오디오를 처리하는 방법을 지정합니다. 후속 요청에 AssistRequest.audio_in바이트가 제공될 경우 필수입니다.

text_query

string

어시스턴트로 전송될 텍스트 입력입니다. 오디오 입력을 사용할 수 없는 경우 텍스트 인터페이스에서 채울 수 있습니다.

AssistRequest

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

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

AssistConfig

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

audio_in

bytes

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

AssistResponse

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

필드
event_type

EventType

출력 전용: 이벤트 유형을 나타냅니다.

audio_out

AudioOut

출력 전용: 쿼리에 대한 어시스턴트의 응답이 포함된 오디오입니다.

screen_out

ScreenOut

출력 전용: 쿼리에 대한 어시스턴트의 시각적 응답을 포함합니다.

device_action

DeviceAction

출력 전용: 적절한 페이로드 및 시맨틱 파싱을 통해 쿼리에 의해 트리거된 작업이 포함됩니다.

speech_results[]

SpeechRecognitionResult

출력 전용 이 반복되는 목록에는 현재 처리 중인 오디오의 연속 부분에 해당하는 0개 이상의 음성 인식 결과가 포함되며, 가장 오래된 오디오부터 가장 안정적인 부분부터 가장 최근 오디오에 해당하는 부분부터 시작됩니다. 문자열을 연결하여 진행 중인 전체 응답을 볼 수 있습니다. 음성 인식이 완료되면 이 목록에 stability가 1.0인 항목 하나가 포함됩니다.

dialog_state_out

DialogStateOut

출력 전용: 사용자의 검색어와 관련된 출력이 포함됩니다.

debug_info

DebugInfo

출력 전용 개발자를 위한 디버깅 정보입니다. 요청이 return_debug_info를 true로 설정한 경우에만 반환됩니다.

EventType

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

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

AudioInConfig

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

필드
encoding

Encoding

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

sample_rate_hertz

int32

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

인코딩

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

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

AudioOut

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

필드
audio_data

bytes

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

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

DebugConfig

현재 요청의 디버깅 매개변수입니다.

필드
return_debug_info

bool

이 필드를 true로 설정하면 AssistResponse의 debug_info 필드가 채워질 수 있습니다. 하지만 응답 지연 시간이 크게 증가합니다.

DebugInfo

개발자를 위한 디버그 정보 요청이 return_debug_info를 true로 설정한 경우에만 반환됩니다.

필드
aog_agent_to_assistant_json

string

Action-on-Google 에이전트에서 Google 서버에 보낸 원본 JSON 응답입니다. AppResponse를 참조하세요. 요청 제조업체가 AoG 프로젝트를 소유하고 AoG 프로젝트가 미리보기 모드인 경우에만 채워집니다.

DeviceAction

사용자가 기기 작업을 트리거한 경우 기기에 반환되는 응답입니다. 예를 들어 조명 켜기 쿼리를 지원하는 기기는 요청의 시맨틱스를 포함하는 JSON 페이로드와 함께 DeviceAction를 수신합니다.

필드
device_request_json

string

트리거된 기기 작업 문법에서 생성된 기기 명령어 응답이 포함된 JSON입니다. 형식은 지정된 트레잇과 관련된 action.devices.EXECUTE 인텐트에서 지정됩니다.

DeviceConfig

필수 어시스턴트가 기기를 식별하는 데 사용하는 필드입니다.

참고 항목

필드
device_id

string

필수 기기의 고유 식별자입니다. ID 길이는 128자(영문 기준) 이하여야 합니다. 예: DBCDW098234. 기기 등록에서 반환된 device_id와 일치해야 합니다(MUST). 이 device_id는 사용자의 등록된 기기와 비교하여 이 기기의 지원되는 특성과 기능을 조회하는 데 사용됩니다. 이 정보는 기기를 재부팅해도 변경되지 않습니다. 하지만 초기화 시에는 저장해서는 안 됩니다.

device_model_id

string

필수 기기 모델의 고유 식별자입니다. device_model_id와 device_id의 조합은 이전에 기기 등록을 통해 연결되었어야 합니다.

DeviceLocation

위치 소스는 세 가지입니다. 이 우선순위는 다음 우선순위로 사용됩니다.

  1. 이 DeviceLocation은 주로 GPS 기능이 있는 휴대기기에 사용됩니다 .
  2. 기기 설정 시 사용자가 지정한 위치로, 사용자 및 기기별로 지정됩니다. DeviceLocation가 지정되지 않은 경우 이 위치가 사용됩니다.
  3. IP 주소를 기반으로 추론한 위치 위의 두 가지 중 어느 것도 지정되지 않은 경우에만 사용됩니다.
필드
coordinates

LatLng

기기의 위도 및 경도입니다.

DialogStateIn

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

필드
conversation_state

bytes

필수 이 필드는 항상 이전 Assist RPC에서 반환된 DialogStateOut.conversation_state 값으로 설정해야 합니다. 이전 Assist RPC가 없는 경우에만 이 값을 생략해야 합니다 (필드가 설정되지 않음). 이는 기기가 처음 설정되거나 초기화된 후 이 기기에서 생성된 첫 번째 Assist RPC이기 때문입니다.

language_code

string

필수 IETF BCP 47 구문으로 된 요청 언어입니다 (예: 'en-US'). 자세한 내용은 언어 지원을 참조하세요. 휴대전화의 Google 어시스턴트 앱의 설정 메뉴를 사용하여 device_id의 언어를 선택한 경우 선택한 언어가 이 값을 재정의합니다.

device_location

DeviceLocation

선택사항 쿼리가 시작된 기기의 위치입니다.

is_new_conversation

bool

선택사항 true인 경우 서버에서 요청을 새 대화로 취급하고 이전 요청의 상태를 사용하지 않습니다. 기기 재부팅 후 또는 이전 쿼리 이후 상당한 시간이 지난 후 대화를 다시 시작해야 하는 경우 이 필드를 true로 설정합니다.

DialogStateOut

사용자 쿼리에서 발생한 대화상자 상태입니다. 이러한 메시지가 여러 개 전송될 수 있습니다.

필드
supplemental_display_text

string

출력 전용 어시스턴트의 추가 표시 텍스트입니다. 이는 AssistResponse.audio_out로 말하는 음성과 같을 수도 있고 사용자가 이해하는 데 도움이 되는 추가 정보일 수도 있습니다.

conversation_state

bytes

출력 전용 후속 Assist RPC의 상태 정보입니다. 이 값은 클라이언트에 저장되고 다음 Assist RPC와 함께 DialogStateIn.conversation_state 필드에 반환되어야 합니다. 클라이언트는 이 값을 해석하거나 달리 사용할 필요가 없습니다. 이 정보는 기기를 재부팅할 때 저장해야 합니다. 하지만 이 값은 초기화 시 클라이언트에 저장되지 않도록 삭제해야 합니다.

microphone_mode

MicrophoneMode

출력 전용 이 Assist RPC가 처리된 후의 마이크 모드를 지정합니다.

volume_percentage

int32

출력 전용 볼륨 수준을 업데이트했습니다. 볼륨 높여 줘 또는 볼륨 4로 설정과 같은 음성 명령이 인식되지 않는 한 이 값은 0이거나 생략 (변경되지 않음을 나타냄)합니다. 이 경우 값은 1에서 100 사이가 됩니다 (1% ~100%의 새로운 볼륨 수준에 해당). 일반적으로 클라이언트는 audio_out 데이터를 재생할 때 이 볼륨 수준을 사용해야 하고 이 값을 현재 볼륨 수준으로 유지하고 다음 AssistRequest의 AudioOutConfig에 제공해야 합니다. (일부 클라이언트는 예를 들어 사용자가 돌릴 수 있는 노브를 제공하는 등 현재 볼륨 수준을 변경할 수 있는 다른 방법을 구현할 수도 있습니다.)

MicrophoneMode

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

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

ScreenOut

쿼리에 대한 어시스턴트의 시각적 출력 응답입니다. screen_out_config님이 사용 설정했습니다.

필드
format

Format

출력 전용 제공된 화면 데이터의 형식입니다.

data

bytes

출력 전용 어시스턴트 쿼리의 결과로 표시될 원시 화면 데이터입니다.

형식

가능한 화면 데이터 형식입니다.

열거형
FORMAT_UNSPECIFIED 지정된 형식이 없습니다.
HTML 데이터에는 UTF-8로 인코딩된 완전한 형식의 HTML5 레이아웃이 포함됩니다(예: <html><body><div>...</div></body></html>). 오디오 응답과 함께 렌더링되도록 만들어졌습니다. HTML5 doctype은 실제 HTML 데이터에 포함되어야 합니다.

ScreenOutConfig

서버가 screen_out 응답을 반환할 때 사용할 원하는 서버 형식을 지정합니다.

필드
screen_mode

ScreenMode

쿼리를 실행하는 동안 기기의 현재 시각적 화면 모드입니다.

ScreenMode

기기의 시각적 화면 출력을 위해 가능한 모드입니다.

열거형
SCREEN_MODE_UNSPECIFIED 지정된 동영상 모드가 없습니다. 어시스턴트가 OFF 모드와 같이 응답할 수 있습니다.
OFF 화면이 꺼져 있음 (또는 밝기 또는 기타 설정이 너무 낮게 설정되어 있어 보이지 않음) 이 모드에서는 일반적으로 어시스턴트가 화면 응답을 반환하지 않습니다.
PLAYING 이 모드에서는 일반적으로 어시스턴트는 부분 화면 응답을 반환합니다.

SpeechRecognitionResult

사용자가 말한 문구의 예상 스크립트입니다. 단일 세그먼트이거나 사용자가 말한 검색어를 완전히 추측한 결과일 수 있습니다.

필드
transcript

string

출력 전용 사용자가 말한 단어를 나타내는 스크립트 텍스트입니다.

stability

float

출력 전용 어시스턴트가 결과에 관한 추측을 변경하지 않을 가능성의 추정치입니다. 값의 범위는 0.0 (완전히 불안정함)~1.0 (완전히 안정된 최종 버전)입니다. 기본값 0.0은 stability가 설정되지 않았음을 나타내는 센티널 값입니다.