Google Assistant Library

แพ็กเกจ google.assistant.library

class google.assistant.library.Assistant(credentials, device_model_id)

ไคลเอ็นต์สําหรับไลบรารี Google Assistant

ให้ฟังก์ชันการควบคุมพื้นฐานและการจัดการวงจรชีวิตของ Google Assistant แนวทางปฏิบัติแนะนำคือให้ใช้ Assistant เป็นContextManager

with Assistant(credentials, device_model_id) as assistant:

ซึ่งช่วยให้การติดตั้งใช้งานแบบเนทีฟที่อยู่เบื้องหลังจัดการหน่วยความจําได้อย่างเหมาะสม

เมื่อเรียก start() แล้ว Assistant จะสร้างสตรีมเหตุการณ์ที่ส่งต่อสถานะต่างๆ ของ Assistant ในขณะนั้น เช่น

ON_CONVERSATION_TURN_STARTED
ON_END_OF_UTTERANCE
ON_RECOGNIZING_SPEECH_FINISHED:
    {'text': 'what time is it'}
ON_RESPONDING_STARTED:
    {'is_error_response': False}
ON_RESPONDING_FINISHED
ON_CONVERSATION_TURN_FINISHED:
    {'with_follow_on_turn': False}

ดูรายละเอียดเกี่ยวกับเหตุการณ์ทั้งหมดและอาร์กิวเมนต์ของเหตุการณ์ได้ที่ EventType

อภิธานศัพท์:

  • คําสั่งให้ดำเนินการ: วลีที่ Assistant จะคอยฟังเมื่อไม่ได้ปิดเสียง

    "OK Google" OR "Hey Google"

  • Turn: คำขอของผู้ใช้รายการเดียวตามด้วยการตอบกลับจาก Assistant

  • การสนทนา: การสนทนาอย่างน้อย 1 ครั้งที่ส่งผลให้ได้ผลลัพธ์ที่ต้องการจาก Assistant

    "What time is it?" -> "The time is 6:24 PM" OR
"Set a timer" -> "Okay, for how long?" ->
"5 minutes" -> "Sure, 5 minutes, starting now!"
พารามิเตอร์ ได้แก่
  • credentials (google.oauth2.credentials.Credentials) – ข้อมูลเข้าสู่ระบบ Google OAuth2 ของผู้ใช้
  • device_model_id (str) – device_model_id ที่ลงทะเบียนไว้สำหรับโปรเจ็กต์ของคุณกับ Google ข้อมูลนี้ต้องไม่ใช่สตริงว่าง
เพิ่ม

ValueError – หาก device_model_id มีค่าเป็น "ไม่มี" หรือว่างเปล่า
device_id

แสดงรหัสอุปกรณ์ที่ Assistant สร้างขึ้น

ค่านี้จะระบุอุปกรณ์ของคุณให้กับเซิร์ฟเวอร์เมื่อใช้บริการต่างๆ เช่น Google Device Actions ระบบจะกรอกพร็อพเพอร์ตี้นี้หลังจากเรียกใช้ start() เท่านั้น

ค่าที่ส่งคืน:รหัสอุปกรณ์เมื่อเรียกstart()แล้ว หรือเป็นสตริงว่างหากยังไม่ได้เรียก
ประเภทการแสดงผลstr
send_text_query(query)

ส่ง |query| ไปยัง Assistant ราวกับว่าผู้ใช้เป็นผู้พูด

ซึ่งจะทํางานเหมือนกับที่ผู้ใช้พูดคําสั่งให้ดำเนินการและทำการค้นหา หรือพูดคำตอบสําหรับคําค้นหาที่ตามมา

พารามิเตอร์ ได้แก่query (str) – ข้อความค้นหาที่จะส่งไปยัง Assistant
set_mic_mute(is_muted)

หยุดไม่ให้ Assistant ฟังคำสั่งให้ดำเนินการ

อนุญาตให้ปิดใช้ Assistant ไม่ให้คอยฟังคำสั่งให้ดำเนินการ ซึ่งจะมีฟังก์ชันการทำงานคล้ายกับปุ่มความเป็นส่วนตัวที่ด้านหลังของ Google Home

วิธีนี้จะใช้งานไม่ได้หากยังไม่ได้เริ่ม Assistant

พารามิเตอร์ ได้แก่is_muted (bool) – True จะหยุดไม่ให้ Assistant ฟังเสียง และ False จะอนุญาตให้เริ่มฟังอีกครั้ง
start()

เริ่ม Assistant ซึ่งรวมถึงการฟังคำสั่งให้ดำเนินการ

เมื่อเรียก start() แล้ว Assistant จะเริ่มประมวลผลข้อมูลจากแหล่งที่มาของเสียง ALSA "เริ่มต้น" เพื่อรอฟังคีย์เวิร์ด ซึ่งจะเป็นการเริ่มบริการอื่นๆ ที่ Assistant มีให้ด้วย เช่น ตัวจับเวลา/การปลุก เรียกเมธอดนี้ได้เพียงครั้งเดียวเท่านั้น เมื่อเรียกแล้ว Assistant จะทำงานต่อไปจนกว่าจะมีการเรียก __exit__

ค่าที่ส่งคืน:คิวเหตุการณ์ที่แจ้งการเปลี่ยนแปลงสถานะของ Assistant
ประเภทการแสดงผลgoogle.assistant.event.IterableEventQueue
start_conversation()

เริ่มการสนทนาใหม่กับ Assistant ด้วยตนเอง

เริ่มทั้งการบันทึกคำพูดของผู้ใช้และส่งไปยัง Google ซึ่งคล้ายกับสิ่งที่เกิดขึ้นเมื่อ Assistant ได้ยินคําสั่งให้ดำเนินการ

วิธีนี้จะใช้งานไม่ได้หากไม่ได้เริ่ม Assistant หรือมีการปิดเสียงไว้

stop_conversation()

หยุดการสนทนากับ Assistant ที่ดำเนินอยู่

Assistant อาจกำลังฟังคำถามของผู้ใช้หรือกำลังตอบกลับ หากไม่มีการสนทนาที่ใช้งานอยู่ การดำเนินการนี้จะใช้งานไม่ได้

class google.assistant.library.event.AlertEvent(event_type, args, **_)

ขยายเหตุการณ์เพื่อเพิ่มการแยกวิเคราะห์ "alert_type"

class google.assistant.library.event.AlertType

ประเภทการแจ้งเตือน

ใช้กับเหตุการณ์ ON_ALERT_STARTED และ ON_ALERT_FINISHED

ALARM = 0

กิจกรรมที่ตั้งค่าไว้สำหรับเวลาสัมบูรณ์ เช่น "03:00 น.ของวันจันทร์"

TIMER = 1

เหตุการณ์ที่ตั้งค่าไว้สำหรับเวลาแบบสัมพัทธ์ เช่น "30 วินาทีนับจากนี้"

class google.assistant.library.event.DeviceActionEvent(event_type, args, **kwargs)

ขยายเหตุการณ์เพื่อเพิ่มพร็อพเพอร์ตี้ "การดําเนินการ"

actions

เครื่องมือสร้างคําสั่งที่จะดําเนินการกับอุปกรณ์ปัจจุบัน

class google.assistant.library.event.Event(event_type, args, **_)

เหตุการณ์ที่ Assistant สร้างขึ้น

type

EventType – ประเภทของเหตุการณ์ที่สร้างขึ้น

args

dict – คู่คีย์/ค่าอาร์กิวเมนต์ที่เชื่อมโยงกับเหตุการณ์นี้

static New(event_type, args, **kwargs)

สร้างเหตุการณ์ใหม่โดยใช้คลาสเหตุการณ์เฉพาะเมื่อจําเป็น

พารามิเตอร์ ได้แก่
  • event_type (int) – รหัสตัวเลขที่สอดคล้องกับเหตุการณ์ใน google.assistant.event.EventType
  • args (dict) – คู่คีย์/ค่าอาร์กิวเมนต์ที่เชื่อมโยงกับเหตุการณ์นี้
  • kwargs (dict) – คู่คีย์/ค่าอาร์กิวเมนต์ที่ไม่บังคับซึ่งเจาะจงสำหรับคลาสเหตุการณ์ที่เชี่ยวชาญด้าน EventType
class google.assistant.library.event.EventType

ประเภทเหตุการณ์

ON_ALERT_FINISHED = 11

บ่งบอกว่าเสียงแจ้งเตือนของ alert_type สิ้นสุดแล้ว

พารามิเตอร์ ได้แก่alert_type (AlertType) – รหัสของ Enum ที่แสดงถึงประเภทของการแจ้งเตือนที่เพิ่งสิ้นสุด
ON_ALERT_STARTED = 10

บ่งบอกว่าการแจ้งเตือนเริ่มดังขึ้นแล้ว

การแจ้งเตือนนี้จะยังคงอยู่จนกว่าจะได้รับ ON_ALERT_FINISHED ที่มี alert_type เดียวกัน มีการแจ้งเตือนที่ใช้งานอยู่ได้เพียงรายการเดียวเท่านั้นในช่วงเวลาหนึ่ง

พารามิเตอร์ ได้แก่alert_type (AlertType) – รหัสของ Enum ที่แสดงประเภทการแจ้งเตือนที่ส่งเสียงอยู่ในปัจจุบัน
ON_ASSISTANT_ERROR = 12

ระบุว่าไลบรารี Assistant พบข้อผิดพลาดหรือไม่

พารามิเตอร์ ได้แก่is_fatal (bool) – หากเป็น "จริง" แสดงว่า Assistant จะกู้คืนไม่ได้และต้องรีสตาร์ท
ON_CONVERSATION_TURN_FINISHED = 9

Assistant จบการเลี้ยวปัจจุบันแล้ว

ซึ่งรวมถึงทั้งการประมวลผลคําค้นหาของผู้ใช้และการพูดคําตอบแบบเต็ม หากมี

พารามิเตอร์ ได้แก่with_follow_on_turn (bool) – หากเป็น "จริง" แสดงว่า Assistant คาดหวังว่าผู้ใช้จะโต้ตอบต่อ ไมโครโฟนจะเปิดขึ้นอีกครั้งเพื่อให้ผู้ใช้ตอบคำถามต่อได้
ON_CONVERSATION_TURN_STARTED = 1

บ่งบอกว่าเริ่มการเลี้ยวใหม่แล้ว

ขณะนี้ Assistant กำลังฟังอยู่เพื่อรอคําค้นหาจากผู้ใช้ ปัญหานี้อาจเกิดจากการได้ยินคำสั่งให้ดำเนินการหรือstart_conversation()ที่เรียกใช้ Assistant

ON_CONVERSATION_TURN_TIMEOUT = 2

Assistant หมดเวลาขณะรอคําค้นหาที่เข้าใจได้

ปัญหานี้อาจเกิดจาก Hotword ทำงานผิดพลาดหรือ Assistant ไม่เข้าใจสิ่งที่ผู้ใช้พูด

ON_DEVICE_ACTION = 14

บ่งบอกว่ามีการส่งคําขอการดำเนินการกับอุปกรณ์ไปยังอุปกรณ์

ระบบจะส่งเหตุการณ์นี้หากมีทริกเกอร์ไวยากรณ์ของอุปกรณ์สําหรับลักษณะที่อุปกรณ์รองรับ เหตุการณ์ประเภทนี้มีพร็อพเพอร์ตี้ "การดำเนินการ" พิเศษ ซึ่งจะแสดงผลคำสั่งตัวนับหรือการดำเนินการกับอุปกรณ์ รวมถึงพารามิเตอร์ที่เกี่ยวข้อง (หากมี)

พารามิเตอร์ ได้แก่dict – เพย์โหลด JSON ที่ถอดรหัสแล้วของคำขอการดำเนินการกับอุปกรณ์
ON_END_OF_UTTERANCE = 3

Assistant หยุดฟังคําค้นหาของผู้ใช้แล้ว

Assistant อาจยังไม่เข้าใจสิ่งที่ผู้ใช้พูด แต่หยุดฟังข้อมูลเสียงเพิ่มเติมแล้ว

ON_MEDIA_STATE_ERROR = 20

บ่งบอกว่าเกิดข้อผิดพลาดขณะเล่นแทร็ก

มีเดียเพลเยอร์ในตัวจะพยายามข้ามไปยังแทร็กถัดไปหรือกลับไปที่ ON_MEDIA_STATE_IDLE หากไม่มีแทร็กใดเหลือให้เล่น

ON_MEDIA_STATE_IDLE = 16

บ่งบอกว่าไม่มีรายการที่กำลังเล่นและไม่มีรายการใดอยู่ในคิวรอเล่น

เหตุการณ์นี้ออกอากาศจากโปรแกรมเล่นสื่อในตัวของคลัง Google Assistant สําหรับข่าว/พอดแคสต์เมื่อเริ่มต้นใช้งาน และเมื่อใดก็ตามที่โปรแกรมเล่นไม่มีการใช้งานเนื่องจากผู้ใช้หยุดสื่อหรือหยุดชั่วคราวและสตรีมหมดเวลา

ON_MEDIA_TRACK_LOAD = 17

บ่งบอกว่าแทร็กกำลังโหลดแต่ไม่เริ่มเล่น

ซึ่งอาจส่งหลายครั้งหากมีการโหลดข้อมูลเมตาใหม่แบบไม่พร้อมกัน ซึ่งโดยปกติจะตามด้วยเหตุการณ์ ON_MEDIA_TRACK_PLAY

พารามิเตอร์ ได้แก่
  • metadata (dict) –

    ข้อมูลเมตาของแทร็กที่โหลด ระบบอาจไม่ได้กรอกข้อมูลในบางช่องภายในเวลานี้ หากไม่ทราบข้อมูลในช่องใด ระบบจะไม่รวมช่องนั้น ช่องข้อมูลเมตามีดังนี้

    album(str): ชื่ออัลบั้มของแทร็ก album_art(str): URL ของภาพปกอัลบั้ม artist(str): ศิลปินที่สร้างแทร็กนี้ duration_ms(double): ความยาวของแทร็กนี้ในหน่วยมิลลิวินาที title(str): ชื่อของแทร็ก
  • track_type (MediaTrackType) – ประเภทของแทร็กที่โหลด
ON_MEDIA_TRACK_PLAY = 18

บ่งบอกว่าแทร็กกำลังส่งออกเสียง

การดำเนินการนี้จะทริกเกอร์ก็ต่อเมื่อเราเปลี่ยนจากสถานะหนึ่งไปยังอีกสถานะหนึ่ง เช่น จาก ON_MEDIA_TRACK_LOAD หรือ ON_MEDIA_TRACK_STOP

พารามิเตอร์ ได้แก่
  • metadata (dict) –

    ข้อมูลเมตาสำหรับแทร็กที่เล่นอยู่ หากไม่ทราบฟิลด์ใด ระบบจะไม่รวมฟิลด์นั้น ช่องข้อมูลเมตา ได้แก่

    album(str): ชื่ออัลบั้มของแทร็ก album_art(str): URL ของภาพปกอัลบั้ม artist(str): ศิลปินที่สร้างแทร็กนี้ duration_ms(double): ความยาวของแทร็กนี้ในหน่วยมิลลิวินาที title(str): ชื่อของแทร็ก
  • position_ms (double) – ตำแหน่งปัจจุบันในแทร็กที่กำลังเล่นเป็นมิลลิวินาทีนับจากต้น หาก "metadata.duration_ms" ไม่ทราบค่า (ตั้งค่าเป็น 0) ระบบจะไม่ตั้งค่าฟิลด์นี้
  • track_type (MediaTrackType) – ประเภทของแทร็กที่กำลังเล่น
ON_MEDIA_TRACK_STOP = 19

บ่งบอกว่าแทร็กก่อนหน้าหยุดเล่นแล้ว

โดยทั่วไปแล้ว สถานะนี้เป็นผลมาจากการที่ผู้ใช้หยุดชั่วคราว แทร็กจะกลับไปที่ ON_MEDIA_TRACK_PLAY ได้หากผู้ใช้เล่นต่อ

พารามิเตอร์ ได้แก่
  • metadata (dict) –

    ข้อมูลเมตาของแทร็กที่ถูกหยุด หากไม่ทราบฟิลด์ใด ระบบจะไม่รวมฟิลด์นั้น ช่องข้อมูลเมตา ได้แก่

    album(str): ชื่ออัลบั้มของแทร็ก album_art(str): URL ของภาพปกอัลบั้ม artist(str): ศิลปินที่สร้างแทร็กนี้ duration_ms(double): ความยาวของแทร็กนี้เป็นมิลลิวินาที title(str): ชื่อของแทร็ก
  • position_ms (double) – ตำแหน่งปัจจุบันในแทร็กหยุดชั่วคราวเป็นมิลลิวินาทีนับจากต้น หาก "metadata.duration_ms" ไม่ทราบค่า (ตั้งค่าเป็น 0) ระบบจะไม่ตั้งค่าฟิลด์นี้
  • track_type (MediaTrackType) – ประเภทของแทร็กที่ถูกหยุด
ON_MUTED_CHANGED = 13

ระบุว่า Assistant กำลังฟังอยู่หรือไม่

start() จะสร้างON_MUTED_CHANGEDเสมอเพื่อรายงานค่าเริ่มต้น

พารามิเตอร์ ได้แก่is_muted (bool) – หากเป็น True แสดงว่า Assistant ไม่ได้กำลังฟังคำสั่งให้ดำเนินการและจะไม่ตอบสนองต่อคําค้นหาของผู้ใช้
ON_NO_RESPONSE = 8

Assistant พูดจนจบรอบแล้ว แต่ไม่มีอะไรจะพูด

ON_RECOGNIZING_SPEECH_FINISHED = 5

Assistant ระบุคำพูดที่จดจำได้สุดท้ายแล้ว

พารามิเตอร์ ได้แก่text (str) – การตีความข้อความสุดท้ายของคําค้นหาของผู้ใช้
ON_RENDER_RESPONSE = 15

บ่งบอกว่า Assistant มีเอาต์พุตข้อความที่จะแสดงผลสำหรับคำตอบ

พารามิเตอร์ ได้แก่
  • type (RenderResponseType) – ประเภทของคำตอบที่จะแสดงผล
  • text (str) – สตริงที่จะแสดงผลสำหรับ RenderResponseType.TEXT
ON_RESPONDING_FINISHED = 7

Assistant ตอบกลับด้วยเสียงเสร็จแล้ว

ON_RESPONDING_STARTED = 6

Assistant กำลังเริ่มตอบกลับด้วยเสียง

Assistant จะตอบกลับจนกว่าจะได้รับการตอบกลับON_RESPONDING_FINISHED

พารามิเตอร์ ได้แก่is_error_response (bool) – จริงหมายถึงกำลังเล่น TTS ข้อผิดพลาดในเครื่องอยู่ ไม่เช่นนั้น Assistant จะตอบกลับด้วยการตอบกลับของเซิร์ฟเวอร์
ON_START_FINISHED = 0

คลัง Assistant เริ่มเสร็จแล้ว

class google.assistant.library.event.IterableEventQueue(timeout=3600)

ขยาย queue.Queue เพื่อเพิ่มอินเทอร์เฟซ __iter__

offer(event)

เสนอกิจกรรมที่จะส่งเข้าคิว

หากคิวเต็มแล้ว ระบบจะบันทึกเหตุการณ์แต่ไม่เพิ่มเหตุการณ์นั้น

พารามิเตอร์ ได้แก่event (Event) – เหตุการณ์ที่จะพยายามเพิ่มลงในคิว
class google.assistant.library.event.MediaStateChangeEvent(event_type, args, **_)

ขยายเหตุการณ์เพื่อเพิ่มการแยกวิเคราะห์ "สถานะ"

class google.assistant.library.event.MediaTrackType

ประเภทแทร็กสําหรับเหตุการณ์ ON_MEDIA_TRACK_X

ใช้กับ ON_MEDIA_TRACK_LOAD, ON_MEDIA_TRACK_PLAY, & ON_MEDIA_TRACK_STOP

CONTENT = 2

เนื้อหาจริงของรายการ (ข่าว/พอดแคสต์)

TTS = 1

บทนำแบบ TTS หรือแทร็กคั่นระหว่างหน้าที่เกี่ยวข้องกับสินค้า

class google.assistant.library.event.RenderResponseEvent(event_type, args, **_)

ขยายเหตุการณ์เพื่อเพิ่มการแยกวิเคราะห์ "response_type"

class google.assistant.library.event.RenderResponseType

ประเภทเนื้อหาที่จะแสดงผล

ใช้กับ ON_RENDER_RESPONSE