Google Home Vitals (Đám mây)

Bộ trang tổng quan và cảnh báo này giúp bạn chủ động duy trì một hoạt động tích hợp chất lượng cao với hệ sinh thái Google Home. Google cam kết hỗ trợ các đối tác trong việc phát triển một hệ sinh thái chất lượng cao cho tất cả khách hàng

Trang tổng quan có 3 phần, mỗi phần đề cập đến một phần chính góp phần vào chất lượng của quá trình tích hợp tổng thể.

  1. Chỉ số từ Google đến đối tác – Đo lường trạng thái của các lệnh gọi từ Google đến phần phụ trợ đám mây của bạn.

  2. Tình trạng hệ thống – Chỉ số về mối quan hệ giữa đối tác và Google – Đo lường tình trạng của các lệnh gọi từ hệ thống của bạn đến Google.

  3. Tình trạng thiết bị – Độ chính xác của trạng thái – Đo lường độ chính xác của các trạng thái được lưu trữ trong hệ thống của Google, được dùng để phân phát các truy vấn của người dùng.

Khi các chỉ số không đạt được giá trị mục tiêu, chúng sẽ được đánh dấu bằng màu đỏ để cho biết có vấn đề có thể ảnh hưởng đến trải nghiệm người dùng. Thông tin sau đây cung cấp thông tin chi tiết về từng mục tiêu và lý do mục tiêu đó quan trọng đối với người dùng của bạn.

Nếu nút sau đây không đưa bạn đến trang tổng quan, bạn có thể truy cập trang tổng quan bằng cách chọn trang Tổng quan, chọn Trang tổng quan rồi chọn Bảng tổng quan Google Home Vitals (Cloud) trong danh sách Trang tổng quan của tôi để xem trang tổng quan.

Chuyển đến Trang tổng quan

Số liệu từ Google đến Đối tác

Chỉ số Tỷ lệ thành công của truy vấn/thực thi >= 99,5% đo lường tần suất người dùng thực hiện đúng các lệnh, giúp tránh các câu trả lời của Trợ lý như "Tôi không thể kết nối với thiết bị" hoặc xác nhận sai một lệnh chưa được thực hiện.

Điều gì định nghĩa một "Thành công"?

Một giao dịch được đánh dấu là thành công nếu nền tảng Google Home nhận được một phản hồi hợp lệ cho biết hành động dự kiến đã được thực hiện hoặc trạng thái được yêu cầu đã được truy xuất.

Những phản hồi bao gồm các trường hợp ngoại lệ không chặn (ví dụ: trạng thái SUCCESS đi kèm với trường hợp ngoại lệ lowBattery) được tính là giao dịch thành công. Lệnh đã đến được thiết bị và ý định đã được đáp ứng mặc dù có cảnh báo.

Điều gì định nghĩa một "Lỗi"?

Những lỗi được tìm thấy trong Mã lỗi thường gặp của nền tảng được đánh dấu là Đối tác có thể thực hiện hành động được coi là "Lỗi" khi tính Tỷ lệ thành công của QUERY và EXECUTE. Ngoài ra, các lỗi được tìm thấy trên Lỗi và ngoại lệ cũng là "Lỗi", ngoại trừ các trường hợp sau:

Trường hợp ngoại lệ khi thất bại
aboveMaximumLightEffectsDuration armLevelNeeded inOffMode
alreadyArmed bagFull lockedToRange
alreadyAtMax belowMinimumLightEffectsDuration lowBattery
alreadyAtMin binFull maxSpeedReached
alreadyClosed cancelArmingRestricted minSpeedReached
alreadyDisarmed deadBattery notSupported
alreadyDocked degreesOutOfRange ngoại tuyến
alreadyInState deviceJammingDetected percentOutOfRange
alreadyLocked deviceNotMounted rangeTooClose
alreadyOff deviceNotReady relinkRequired
alreadyOn deviceOffline remoteSetDisabled
alreadyOpen deviceTurnedOff safetyShutOff
alreadyPaused discreteOnlyOpenClose targetAlreadyReached
alreadyStarted functionNotSupported tooManyFailedAttempts
alreadyStopped inAutoMode valueOutOfRange
alreadyUnlocked inEcoMode

Chỉ số Độ trễ truy vấn/thực thi (p90) <= 1000 mili giây đo lường thời gian chờ của hành động được yêu cầu và giúp đảm bảo người dùng không phải chờ quá lâu, ví dụ: chờ vài giây để đèn tắt.

Chỉ số về độ trễ

Độ trễ là một chỉ báo quan trọng cho biết mức độ phản hồi của hoạt động tích hợp đối với người dùng cuối. Trang tổng quan theo dõi Độ trễ ở phân vị thứ 90 (P90), thể hiện trải nghiệm của những người dùng "chậm nhất" (ví dụ: P90 là 800 mili giây có nghĩa là 90% yêu cầu được xác nhận trong vòng 800 mili giây hoặc ít hơn).

Google đo độ trễ theo cách khác nhau đối với các lệnh kiểm tra trạng thái so với lệnh thiết bị để đảm bảo độ chính xác về kỹ thuật.

1. Độ trễ của truy vấn (Nghi vấn)

Chỉ số này đo thời gian khứ hồi Cloud-to-cloud khi Google yêu cầu trạng thái hiện tại của một thiết bị.

  • Bắt đầu: Google gửi một yêu cầu action.devices.QUERY đến URL thực hiện của bạn.
  • Khoảng thời gian đo lường: Thời gian cần thiết để đám mây của bạn nhận, xử lý và truyền toàn bộ phản hồi HTTP trở lại Google.
  • Kết thúc: Google nhận và xác nhận tải trọng phản hồi cuối cùng từ dịch vụ của bạn.

2. Độ trễ EXECUTE (Hành động)

Chỉ số này đo thời gian phản hồi lệnh khi Google gửi yêu cầu điều khiển đến một thiết bị.

  • Bắt đầu: Google gửi một yêu cầu action.devices.EXECUTE đến URL thực hiện của bạn.
  • Khoảng thời gian đo: Khoảng thời gian cần thiết để đám mây của bạn nhận được lệnh và trả về một phản hồi xác nhận.
  • Kết thúc: Google nhận được phản hồi trạng thái SUCCESS, PENDING hoặc OFFLINE.
  • Phạm vi kỹ thuật: Chỉ số này đo lường thời gian "Response Ack" giữa đám mây của Google và đám mây của bạn. API này không đo lường thời gian cần thiết để phần cứng thực (ví dụ: bóng đèn) hoàn tất quá trình thay đổi trạng thái thực, vì quá trình này thường liên quan đến độ trễ của mạng lưới cục bộ bên ngoài đường dẫn từ đám mây đến đám mây.

Các lựa chọn giảm độ trễ

Đề xuất về cấu trúc cho tính năng định tuyến theo vị trí địa lý

Nếu không thể triển khai IP Anycast, bạn nên dùng các giải pháp thay thế hiệu quả về chi phí sau đây để đảm bảo người dùng được phục vụ bởi trung tâm dữ liệu khu vực gần nhất.

  1. Cân bằng tải toàn cầu (GLB)

    Thay vì định tuyến tĩnh, hãy sử dụng Global Application Load Balancer (có sẵn từ hầu hết các nhà cung cấp dịch vụ đám mây lớn).

    • Cách hoạt động: Bạn định cấu hình một điểm truy cập toàn cầu duy nhất (URL) nằm ở rìa mạng. Trình cân bằng tải sẽ tự động phát hiện nguồn gốc địa lý của yêu cầu từ các cụm thực hiện của Google và định tuyến lưu lượng truy cập đến phần phụ trợ khu vực hoạt động gần nhất.

    • Lợi ích: Điều này mang lại hiệu suất của Anycast với chi phí và độ phức tạp của cấu hình thấp hơn đáng kể.

  2. DNS nhận biết vị trí địa lý (GeoDNS)

    • Cách hoạt động: Định cấu hình nhà cung cấp DNS để phân giải URL thực hiện đơn hàng thành các địa chỉ IP khác nhau dựa trên vị trí địa lý của truy vấn DNS.

    • Triển khai: Đảm bảo nhà cung cấp DNS của bạn được tối ưu hoá cho các điểm thoát của Google. Khi các dịch vụ thực hiện theo khu vực của Google (ví dụ: ở Hoa Kỳ, Liên minh Châu Âu hoặc Châu Á) phân giải miền của bạn, các dịch vụ này sẽ nhận được địa chỉ IP cho trung tâm dữ liệu ở khu vực cụ thể đó.

Chiến lược tối ưu hoá ở lớp ứng dụng

Ngoài việc định tuyến ở cấp cơ sở hạ tầng, bạn có thể triển khai các chiến lược sau ở lớp ứng dụng để giảm độ trễ trong quá trình xử lý yêu cầu.

  1. Phương pháp proxy "Trampoline"

    Nếu bạn phải duy trì một trung tâm dữ liệu chính, hãy sử dụng các máy chủ proxy gọn nhẹ theo khu vực (Trampolines) để xử lý bước bắt tay ban đầu.

    1. Google truy cập vào URL chung của bạn.

    2. Một proxy theo khu vực (ví dụ: hàm Nginx hoặc Lambda đơn giản) sẽ nhận yêu cầu.

    3. Proxy chuyển tiếp tải trọng qua mạng trục nội bộ, tốc độ cao đến cơ sở dữ liệu chính.

    Lợi ích: Điều này giúp giảm thời gian "Bắt tay TCP", thường là yếu tố đóng góp lớn nhất vào độ trễ cho các yêu cầu ở khoảng cách xa.

  2. Gợi ý về khu vực mã truy cập

    Trong quá trình Liên kết tài khoản (OAuth), hệ thống của bạn có thể xác định khu vực cư trú của người dùng.

    Triển khai: Mã hoá giá trị nhận dạng khu vực vào access_token được phát hành cho Google. Khi Google gửi yêu cầu thực hiện đơn hàng, cổng của bạn có thể kiểm tra ngay mã thông báo và định tuyến yêu cầu đến đúng cụm theo khu vực mà không cần tra cứu cơ sở dữ liệu.

Tình trạng hệ thống – Chỉ số đối tác với Google

Duy trì Tỷ lệ thành công >= 99, 5% giúp đảm bảo rằng trạng thái thiết bị chính xác trong Google Home, thiết bị được thêm và xoá, quy trình tự động hoá kích hoạt và các sự kiện trong nhật ký xuất hiện trong thẻ Hoạt động của Google Home app (GHA).

Tỷ lệ thành công được tính dựa trên mã phản hồi HTTP mà Google trả về khi đám mây của bạn gửi các bản cập nhật trạng thái. Để đảm bảo đối tác không bị phạt vì các vấn đề về cơ sở hạ tầng phía Google, chỉ số này sẽ loại trừ các lỗi nội bộ của Google khỏi số lượng lỗi. Các lệnh gọi API có trong phép tính này nằm trong tài liệu tham khảo HomeGraph API.

Điều gì định nghĩa một "Thành công"?

2xx (Thành công): Home Graph đã nhận và xử lý thành công nội dung cập nhật trạng thái.

Điều gì định nghĩa một "Lỗi"?

4xx (Lỗi đối tác) biểu thị các lỗi và cho biết có vấn đề với yêu cầu được gửi từ đám mây của bạn. Các mã phổ biến bao gồm:

400 Yêu cầu không hợp lệ

Nguyên nhân: Máy chủ không thể xử lý yêu cầu do cú pháp không hợp lệ. Các nguyên nhân phổ biến bao gồm JSON bị lỗi hoặc sử dụng giá trị rỗng thay vì "" cho giá trị chuỗi.

Giải pháp: Đảm bảo rằng nội dung yêu cầu là JSON hợp lệ (không có cấu trúc bị lỗi hoặc giá trị rỗng cho các trường chuỗi) và xác minh rằng agentUserId khớp với giá trị trong phản hồi SYNC.

404 Không tìm thấy

Nguyên nhân: Không tìm thấy deviceId hoặc agentUserId trong HomeGraph (chưa được đồng bộ hoá, đã huỷ liên kết hoặc không khớp mã nhận dạng).

Giải pháp:

  1. Đảm bảo rằng agentUserId khớp với giá trị được cung cấp trong phản hồi SYNC.
  2. Sử dụng Home Graph SYNC API để xác định xem lỗi 404 Không tìm thấy có phải do thiếu thiết bị hoặc người dùng trong HomeGraph hay không.
  3. Đảm bảo kích hoạt requestSync sau khi thêm, xoá, đổi tên hoặc cập nhật thiết bị hoặc tài khoản để đảm bảo trạng thái luôn được cập nhật.
  4. Xử lý đúng cách các ý định DISCONNECT để ngừng báo cáo các thiết bị cũ. Sau khi nhận được ý định DISCONNECT, dịch vụ đám mây của bạn sẽ ngừng xuất bản các thay đổi cho Google bằng Request SyncReport State.

429 Đã hết tài nguyên

Nguyên nhân: Mức sử dụng của chế độ tích hợp đã vượt quá hạn mức được phân bổ.

Giải pháp: Xem hướng dẫn trong phần "Bước 2a: Gỡ lỗi về hạn mức" trong trang tổng quan để quản lý hạn mức. Bạn cũng có thể tham khảo Hạn mức và giới hạn của Nhà thông minh để biết thêm thông tin.

Tình trạng thiết bị – Độ chính xác của trạng thái

Việc đáp ứng hoặc vượt quá Độ chính xác của trạng thái >= 99,5% giúp đảm bảo người dùng thấy kết quả chính xác khi xem trạng thái thiết bị hoặc sử dụng các tính năng AI như Hỏi Home. Nếu độ chính xác của trạng thái thấp, các hoạt động tự động có thể không kích hoạt và các mục trong nhật ký có thể không xuất hiện trong thẻ Hoạt động của GHA vào đúng thời điểm. Để biết thêm thông tin, hãy xem phần Báo cáo trạng thái.

Trang tổng quan về chất lượng theo dõi chỉ số này theo giờ bằng cách sử dụng 2 chỉ số riêng biệt: Độ chính xác tổng thểTổ hợp Loại/Đặc điểm thấp nhất.

1. Thành phần độ chính xác

Chỉ số này được lấy từ "mẫu" mà Google có thể xác minh trạng thái được báo cáo dựa trên kết quả dự kiến đã biết.

2. Chỉ số trên trang tổng quan (Tính toán theo giờ)

Trang tổng quan tính toán độ chính xác dựa trên khoảng thời gian 1 giờ. Nếu một giờ có tổng số mẫu dưới 100 (S_Total < 100), thì độ chính xác cho giờ đó sẽ được đặt thành N/A.

Chế độ xem 1: Độ chính xác tổng thể (Trung bình toàn cầu)

Đây là độ chính xác tổng thể của quá trình tích hợp trên tất cả các loại thiết bị và đặc điểm kết hợp. Chỉ số này cung cấp giá trị trung bình có trọng số về tình trạng của toàn bộ hệ sinh thái.

  • Cách tính: Tổng số trạng thái chính xác trên tất cả thiết bị / Tổng số trạng thái trên tất cả thiết bị.

Chế độ xem 2: Tổ hợp kiểu/đặc điểm thấp nhất

Điều này xác định danh mục cụ thể không đáng tin cậy nhất trong quá trình tích hợp. Điều này ngăn các thiết bị có số lượng lớn và chất lượng cao che giấu các thiết bị có số lượng ít và chất lượng thấp. Ví dụ: nếu bạn có số lượng đèn lớn với Độ chính xác về trạng thái trên 99, 5%, nhưng số lượng Công tắc thấp với Độ chính xác về trạng thái thấp, thì điều này cho thấy cần cải thiện công tắc có thể bị mất trong giá trị trung bình.

  • Tính toán: Giá trị tối thiểu của Độ chính xác theo trạng thái / Tổng số trạng thái cho tất cả các tổ hợp đặc điểm/thiết bị.

3. Cải thiện độ chính xác về tình trạng và trạng thái của thiết bị

Sự khác biệt xảy ra khi trạng thái được lưu trữ trong Home Graph không khớp với kết quả của một QUERY theo thời gian thực.

Lỗi "Thiếu trường"

Ví dụ về DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

Ví dụ về DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

Nguyên nhân: Với lỗi DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD hoặc DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, tập hợp các trường tải trọng khác nhau giữa phản hồi QUERY và yêu cầu Trạng thái báo cáo của bạn cho cùng một thiết bị.

Giải pháp: Đảm bảo cấu trúc dữ liệu giống nhau ở cả hai đường dẫn. Nếu một đặc điểm được đưa vào SYNC, thì các trường tương ứng của đặc điểm đó phải xuất hiện và nhất quán trong cả báo cáo chủ động và truy vấn phản hồi.

Lỗi "Không chính xác"

Ví dụ về DETAILED_ACCURACY_RESULT_INACCURATE

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

Nguyên nhân: Đối với lỗi DETAILED_ACCURACY_RESULT_INACCURATE, có sự khác biệt giữa giá trị được trả về trong phản hồi QUERY và giá trị Trạng thái báo cáo cuối cùng.

Giải pháp: Đảm bảo Report State được kích hoạt bất cứ khi nào trạng thái thiết bị thay đổi và cả Report State cũng như QUERY luôn cung cấp các giá trị chính xác, mới nhất và tất cả các trường bắt buộc để duy trì tính nhất quán của dữ liệu.

Ví dụ về DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

Nguyên nhân: Khi gặp lỗi DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, đối tác đã thực thi lệnh thành công nhưng không báo cáo trạng thái thiết bị mới nhất cho Google.

Giải pháp: Luôn gửi thông tin cập nhật về Trạng thái báo cáo sau khi thực thi lệnh để Home Graph nhận được trạng thái thiết bị mới.

Ví dụ về DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

Nguyên nhân: Đối với lỗi DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, không có ReportState nào được nhận cho thiết bị này (trạng thái trống và dấu thời gian được báo cáo là tại thời điểm bắt đầu, mặc dù kết quả QUERY cung cấp trạng thái hiện tại. Điều này cho biết các thông tin cập nhật trạng thái không được kích hoạt, không thể truy cập vào HomeGraph hoặc thiết bị không báo cáo thành công các trạng thái chuyển đổi trong khả năng kết nối hoặc trạng thái hoạt động.

Giải pháp: Đảm bảo Report State được kích hoạt và gửi thành công cho tất cả các thay đổi về trạng thái. Xác minh rằng logic phụ trợ xử lý chính xác các thông tin cập nhật trạng thái, xác nhận việc phân phối thành công cho Google HomeGraph và đảm bảo thiết bị liên tục đồng bộ hoá trạng thái để duy trì giao diện người dùng và công cụ tự động hoá một cách chính xác.