Code

Quick Automate 中的程式碼動作可讓您使用 Python 程式碼區塊實作自訂邏輯，超越標準自動化動作支援的範圍。它們非常適合複雜的資料轉換和計算，並在受限的 Python 環境中執行，以維護安全性。

兩種類型的程式碼動作：

• 單行表達式：快速的單行操作，可修改變數而不傳回值

• 自訂程式碼區塊：具有參數和傳回值的複雜邏輯的多行 Python 函數

何時使用程式碼動作：

當您需要以下項目時，請使用程式碼區塊：

• 執行標準動作中無法使用的複雜資料轉換

• 實作自訂商業邏輯或計算

• 處理或操作資料結構 （清單、字典、JSON)

• 以自訂方式使用日期、時間和時區

• 複雜模式的剖析或格式字串

• 透過將多個動作合併為一個程式碼區塊來最佳化自動化效能

不使用程式碼動作時：

避免程式碼區塊發生下列情況：

• 您的使用案例已存在標準自動化動作

• 操作簡單到足以執行內建動作

• 您需要與外部 APIs互動 （改用 REST API 整合）

• 您需要存取檔案系統或資料庫 （使用適當的整合）

如何存取程式碼動作：

程式碼區塊可透過多個界面取得：

• 動作面板 （建議）：

  • 在自動化建置器中開啟您的自動化

  • 按一下右側的動作面板

  • 在程式碼動作區段下找到「自訂程式碼區塊」

  • 將程式碼區塊拖放到您的自動化工作流程

• 使用助理建置：

  • 當助理判斷需要自訂程式碼時，可在計劃產生期間使用

  • 助理會自動建議複雜操作的程式碼區塊

  • 您可以透過描述您的自訂邏輯需求來請求程式碼區塊

可用的動作：

單行表達式

單行表達式會執行執行操作的單行 Python 陳述式，而不會傳回值。它們非常適合快速修改現有變數，例如附加至清單、更新字典，或執行修改狀態的簡單計算。

屬性：

• 表達式 （必要）：要執行的 Python 表達式 （例如 "my_list.append('new item')")

範例：

• 附加至清單

  my_list.append("1")
  my_list.append(new_item)

• 移除清單項目

  task_list.remove(completed_task)

自訂程式碼區塊

自訂程式碼區塊是執行複雜邏輯、接受參數和傳回值的多行 Python 函數。當標準自動化動作和單行表達式不足以滿足您的需求時，它們是備用選項。

屬性：

• 函數標題 （必要）：程式碼區塊的名稱識別符 （例如 "Calculate_Total")

• 函數 （必要）：包含自訂邏輯的 Python 程式碼區塊。

  • 步驟 1：定義參數

    • 按一下「編輯」按鈕以開啟程式碼編輯器

    • 在參數面板中，按一下「新增」建立新的參數

    • 輸入符合您自動化變數的參數名稱

    • 參數可作為函數引數使用

  • 步驟 2：撰寫您的 Python 程式碼

• 傳回值 （選用）：儲存函數輸出的變數名稱

  • 遵循必要的程式碼區塊結構 （請參閱下文）

  • 在 函數中實作您的自訂邏輯

  • 僅使用核准的程式庫和內建函數

  • 如果您需要輸出資料，請包含傳回陳述式

程式碼區塊結構

所有程式碼區塊必須遵循此特定格式：

@code_block()
def your_function_name(parameter1, parameter2, parameter3):
-------------------------------------------------------------------------------------
    """
    Optional: Add a docstring describing what your function does
    """
    # Your custom logic here
    result = parameter1 + parameter2 + parameter3

    return result

內建 Python 函數和匯入

所有標準 Python 內建函數都可以在沒有匯入的情況下使用 (len、str、int 等）

核准的標準程式庫 （受安全性限制）

程式碼區塊只能匯入下列標準程式庫：

• base64 - Base64 編碼/解碼

• datetime - 日期和時間操作

• json - JSON 剖析和產生

• math - 數學函數

• re - 規則表達式

• zoneinfo - 時區處理

注意

• 無法匯入上面列出的標準程式庫以外的標準程式庫。

• 無法安裝或匯入第三方程式庫。程式碼區塊pip install不支援 。

限制

• 具有有限程式庫存取權的受限 Python 環境。執行環境是以 RestrictedPython 為基礎，這是 Python 3.10 的子集。

• 程式碼區塊無法叫用其他程式碼區塊或動作

最佳實務

• 保持程式碼區塊簡單且專注

• 使用描述性函數名稱

• 在可用時，一律偏好預先建置的動作

• 徹底測試程式碼區塊，因為重點偵錯選項有限）

範例 使用案例

• 數學運算 （計算圓形屬性 - 半徑作為參數

  def function
  (radius):
  
      return {
          "radius": radius,
          "diameter": 2 * radius,
          "circumference": round(2 * math.pi * radius, 2),
          "area": round(math.pi * radius ** 2, 2)
      }

• 取得目前日期/時間

  def function
  ():
  
      now = datetime.datetime.now()
  
      return {
          "current_date": now.strftime("%Y-%m-%d"),
          "current_time": now.strftime("%H:%M:%S"),
          "formatted": now.strftime("%B %d, %Y at %I:%M %p"),
          "iso_format": now.isoformat(),
          "timestamp": now.timestamp()
      }

• 計算日期差異 - 開始日期和結束日期作為參數

  def function
  _(start_date_str, end_date_str):
  
  # Parse date strings (format: YYYY-MM-DD)_
      start = datetime.datetime.strptime(start_date_str, "%Y-%m-%d")
      end = datetime.datetime.strptime(end_date_str, "%Y-%m-%d")
  
      _# Calculate difference_
      difference = end - start
      return {
          "days": difference.days,
          "weeks": difference.days // 7,
          "start": start_date_str,
          "end": end_date_str    }

• 使用規則表達式的模式比對和文字處理 （驗證電子郵件地址、電話號碼等）

  def function
  (email, phone, zip_code):
  
      email_pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
      phone_pattern = r'^\d{3}-\d{3}-\d{4}$'
      zip_pattern = r'^\d{5}(-\d{4})?$'
  
      return {
          "email_valid": bool(re.match(email_pattern, email)),
          "phone_valid": bool(re.match(phone_pattern, phone)),
          "zip_valid": bool(re.match(zip_pattern, zip_code))
      }

• 清單操作 （篩選條件和轉換清單）

  def function
  (numbers, threshold):
  
      # Filter numbers above threshold and calculate statistics
      filtered = [n for n in numbers if n > threshold]
  
      if filtered:
          return {
              "filtered_numbers": filtered,
              "count": len(filtered),
              "sum": sum(filtered),
              "average": sum(filtered) / len(filtered),
              "min": min(filtered),
              "max": max(filtered)
          }
      else:
          return {
              "filtered_numbers": [],
              "count": 0,
              "message": "No numbers above threshold"
          }