Tổng quan về Automation API trên Android

Tính năng tự động hoá giúp tự động hoá các công việc và chế độ cài đặt thiết bị trong nhà. Các quy trình tự động hoá đã có trong hệ sinh thái Google Home dưới dạng Quy trình trong Google Home app (GHA) và thông qua automation script editor trên Google Home for web.

Giờ đây, bạn có thể sử dụng các quy trình tự động hoá trong hệ sinh thái Google Home thông qua Home API cho Android. Các quy trình này sử dụng cùng những khái niệm cơ bản như trong Quy trình GHA và script editor, nhưng có các tính năng và chức năng nâng cao chỉ có thể thực hiện thông qua Home API, bao gồm:

• Quyền truy cập vào tất cả các đặc điểm tiêu chuẩn Matter và smart home cho một thiết bị, như được trình bày trong Home API.
• Hỗ trợ các luồng thực thi tuần tự, song song và chọn lọc.

Các quy trình tự động hoá được viết bằng Automation DSL, một ngôn ngữ dành riêng cho miền được thiết kế để tạo quy trình tự động hoá trong Kotlin.

Mọi đặc điểm và loại mà bạn dự định sử dụng trong ứng dụng của mình bằng Device & Structure hoặc Automation API đều phải được đăng ký khi khởi tạo. Xem phần Khởi động trang chủ trên Android.

Hướng dẫn nếu người dùng thu hồi toàn bộ quyền

Nếu người dùng thu hồi toàn bộ quyền, tất cả các quy trình tự động hoá hiện có sẽ ngừng hoạt động. Ngoài ra, nếu người dùng thu hồi quyền truy cập vào các thiết bị cụ thể, thì các điều kiện bắt đầu, điều kiện và hành động liên kết với những thiết bị đó sẽ ngừng hoạt động.

Mỗi khi ứng dụng khởi động, hãy nhớ kiểm tra để đảm bảo các quyền vẫn còn hiệu lực. Nếu các mã thông báo này đã bị thu hồi, hãy đảm bảo rằng bạn đã xoá tất cả dữ liệu trước đó, bao gồm cả mọi dữ liệu được lưu vào bộ nhớ đệm trong ứng dụng.

Khi quyền truy cập vào nhà bị thu hồi, một StructureAccessRevokedEvent sẽ được gửi đến phần phụ trợ đám mây của bạn. Tham khảo phần Cấu trúc cấp quyền để biết quy trình thu hồi quyền truy cập vào ứng dụng di động và đám mây của đối tác từ đầu đến cuối.

Hành trình của nhà phát triển

Automation API là một phần trong hành trình phát triển rộng lớn hơn. Việc này diễn ra sau khi bạn tích hợp Structure API và Device API để đảm bảo rằng người dùng có thể sử dụng một quy trình tự động hoá khi muốn.

1. Nhà phát triển lên kế hoạch tự động hoá và xác định kế hoạch đó bằng cách sử dụng Automation DSL.
2. Nhà phát triển nhúng định nghĩa về quy trình tự động hoá vào một ứng dụng Android Kotlin.
3. Ứng dụng này cung cấp các hoạt động tự động hoá cho người dùng dựa trên thông tin về thiết bị của họ, bao gồm các đặc điểm, thuộc tính, lệnh và sự kiện, được thu thập bằng Discovery API hoặc Device API.
   1. Với Discovery API, ứng dụng có thể tạo một bản nháp tự động hoá được tuỳ chỉnh theo các loại và đặc điểm thiết bị có trong cấu trúc của người dùng, có hoặc không có thông tin đầu vào của người dùng.
   2. Device API có thể cung cấp hầu hết thông tin tương tự như Discovery API, nhưng không được tối ưu hoá cho các trường hợp sử dụng tự động hoá. Hãy xem phần So sánh Device API và Discovery API để biết thêm thông tin chi tiết.
4. Ứng dụng này tạo ra quy trình tự động hoá thực tế được liên kết với cấu trúc đã chọn.
5. Giờ đây, quy trình tự động hoá có trong cấu trúc của người dùng và có thể được thực thi hoặc xoá bằng các phương thức Structure API.

Người dùng có thể tạo các phiên bản mới của quy trình tự động hoá bất cứ lúc nào, chọn một cấu trúc khác hoặc, tuỳ thuộc vào logic của ứng dụng, có thể là một nhóm thiết bị khác. Mỗi lần người dùng thực hiện thao tác này, ứng dụng sẽ tạo một phiên bản mới của quy trình tự động hoá.

Trong trường hợp cơ bản nhất, bạn có thể đề xuất cho người dùng một quy trình tự động hoá được xác định trước để thực hiện một tác vụ tương đối cơ bản. Ngoài ra, bạn có thể trình bày một cấu trúc cơ bản của quy trình tự động hoá mà người dùng tuỳ chỉnh để đáp ứng nhu cầu của họ. Hoặc bạn có thể viết một trình chỉnh sửa tự động hoá mở cho phép người dùng tạo các quy trình tự động hoá phức tạp bằng cách sử dụng tất cả các khối xây dựng có trong Automation API.

Đề xuất về quy trình tự động hoá

Home API có thể đề xuất các quy trình tự động hoá cho Structure dựa trên các yếu tố như loại thiết bị có trong không gian.

Đề xuất tự động hoá được biểu thị bằng lớp AutomationSuggestion.

Giao diện Structure bao gồm giao diện HasSuggestions. Giao diện này cung cấp hàm suggestions(), hàm này trả về một tập hợp các đề xuất tự động hoá.

Các phương thức likeSuggestion() và dislikeSuggestion() được thiết kế để kết nối với các thành phần điều khiển trên giao diện người dùng thumb_up và thumb_down mà người dùng có thể nhấn để đưa ra ý kiến phản hồi.

Phương thức thứ ba, clearSuggestionFeedback(), cho phép người dùng xoá ý kiến phản hồi của họ về một đề xuất tự động hoá.

Ý kiến phản hồi của người dùng sẽ ảnh hưởng đến các đề xuất trong tương lai.

Ví dụ này minh hoạ cách truy xuất các đề xuất tự động hoá hiện có cho Structure, trích xuất một mã đề xuất và ghi lại ý kiến phản hồi của người dùng bằng likeSuggestion(), clearSuggestionFeedback() và dislikeSuggestion().

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch

class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {

  fun loadAndGiveFeedback() {
    viewModelScope.launch {
      // 1. Fetch suggestions from structure
      val suggestions = structure.suggestions()
      val firstSuggestion = suggestions.firstOrNull() ?: return@launch

      // Extract string suggestion ID
      val suggestionId: String = firstSuggestion.id.id

      // 2. Like the suggestion (thumbs up)
      val liked = structure.likeSuggestion(suggestionId)

      // 3. Clear previous feedback if the user toggled it off
      if (liked) {
        structure.clearSuggestionFeedback(suggestionId)
      }

      // 4. Dislike the suggestion (thumbs down)
      structure.dislikeSuggestion(suggestionId)
    }
  }
}

Tham số lệnh động

Các tham số lệnh động cho phép nhà phát triển tạo các tham số hành động được phân giải linh động trong thời gian chạy thay vì chỉ dựa vào các giá trị tĩnh, hằng số. Điều này cho phép 2 chức năng chính:

• Các tham chiếu truyền giá trị của một thuộc tính từ một điều kiện khởi động (chẳng hạn như tải trọng sự kiện) hoặc nút trình đọc trạng thái, hoặc từ các biến cục bộ được khai báo trong quy trình tự động hoá.
• Các biểu thức ghi lại các giá trị động trong thời gian chạy (chẳng hạn như một thuộc tính sự kiện hoặc giá trị trạng thái) và truyền giá trị động trực tiếp vào một tham số lệnh.

Trường hợp sử dụng

Liên kết một công tắc xoay vật lý gửi sự kiện nhấn nhiều lần đến một đèn có thể điều chỉnh độ sáng. Số lượt nhấp là giá trị động được truyền vào lệnh LevelControl ở bước trong thời gian chạy.

Cách hoạt động của tham số động

Trong Automation DSL trên Android, các tham số lệnh chấp nhận các thực thể Expression hoặc Reference ngay tại chỗ thay vì các giá trị hằng số tĩnh. DSL đóng gói những định nghĩa này vào Parameter khi tạo quy trình tự động hoá.

Các quy tắc xác thực

Các tham số lệnh động tuân theo những ràng buộc xác thực sau:

• Các tham số động được giả định là hợp lệ về cấu trúc trong quá trình khám phá vì các API khám phá chỉ đánh giá các ràng buộc giá trị cụ thể cho các đối số tĩnh.
• Các nút tham chiếu hoặc biểu thức phải xuất hiện ở phía trên trong biểu đồ tự động hoá trước khi được tham chiếu trong một thao tác lệnh ở phía dưới.

Sử dụng các tham số lệnh động trên Android

Truyền trực tiếp các biểu thức động vào tham số lệnh:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val keypressAutomation = automation {
  name = "Dynamic command parameters example"
  description = "Pass starter event field directly to command"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountExpr,
        )
      )
    }
  }
}

Ngoài ra, hãy chỉ định một biểu thức cho khai báo biến cục bộ và tham chiếu biến đó sau này trong luồng:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val myAutomationWithVariable = automation {
  name = "Dynamic command parameters with variables"
  description = "Declare a variable, assign value, and pass reference"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    val clickCountVar = variable<UInt>()
    clickCountVar.assign(clickCountExpr)

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountVar,
        )
      )
    }
  }
}

Hạn chế về loại

Đảm bảo rằng các loại biến và biểu thức phù hợp với định nghĩa loại giản đồ Matter bắt buộc của tham số lệnh nhận (chẳng hạn như UShort, UByte hoặc UInt8).

Giới hạn về tài nguyên

Các hạn mức sau đây áp dụng cho quy trình tự động hoá trong Home API: