資料對應工作

您可以使用「資料對應」工作在整合作業中指派變數、取得及設定 JSON 物件的屬性，以及對值套用巢狀轉換函式。變數可以是整合變數或工作變數。

舉例來說，您可以將整合變數 X 的值指派給工作變數 Y，也可以將工作變數 Y 的值指派給整合變數 X。如要進一步瞭解 Application Integration 中的變數，請參閱「 在 Application Integration 中使用變數」。

設定資料對應工作

如要設定「資料對應」工作，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Application Integration」頁面。

   前往 Application Integration

2. 在導覽選單中，按一下「整合」。

   系統會顯示「整合」頁面，列出 Google Cloud 專案中可用的所有整合項目。

3. 選取現有整合，或按一下「建立整合」建立新整合。

   如要建立新的整合項目：

   1. 在「建立整合」窗格中輸入名稱和說明。
   2. 選取整合作業的區域。
      注意：「區域」下拉式選單只會列出 Google Cloud 專案中佈建的區域。如要佈建新區域，請按一下「啟用區域」。詳情請參閱「啟用新地區」。
   3. 選取整合的服務帳戶。如要變更或更新整合的服務帳戶詳細資料，請隨時前往整合工具列的「整合摘要」窗格。
      注意：只有在您為所選區域啟用整合控管功能時，系統才會顯示選取服務帳戶的選項。
   4. 點按「Create」(建立)。新建立的整合服務會在整合服務編輯器中開啟。

4. 在整合編輯器的導覽列中，按一下「Tasks」(工作)，即可查看可用工作和連結器的清單。
5. 在整合服務編輯器中，點按並放置「資料對應」元素。
6. 在設計工具中，按一下「資料對應」元素，即可查看「資料對應」工作設定窗格。
7. 按一下「開啟資料對應編輯器」，即可查看工作的預設值並新增對應。 如需新增對應的詳細步驟，請參閱「新增對應」。

   如要進一步瞭解資料對應編輯器版面配置，請參閱「 資料對應總覽」。

新增對應

如要新增對應，請完成下列步驟：

1. 在「資料對應」工作設定窗格中，按一下「開啟資料對應編輯器」。
2. 設定對應的「輸入」：
   「輸入」：資料對應輸入的來源。來源可以是常值、基本函式或輸入變數，並搭配對應函式。
   1. 從「變數」清單中，將變數或其子欄位拖曳到「輸入」列。如要查看變數的可用子欄位，請在「變數」清單中，按一下該變數旁的「展開」圖示 。
   2. 或者，在「輸入」列中，按一下「變數或值」，然後執行下列操作：
      • 選取「變數」，搜尋並使用現有變數。 如要建立新變數，請按一下「+ 新增變數」，然後輸入新變數的名稱和資料型別。
      • 選取「值」，輸入 string、integer、double 或 Boolean 類型的字面值。
      • 選取「函式」，搜尋及使用基本函式。

        在整合執行期間，系統會使用基本函式擷取或產生值。例如產生隨機 UUID 或擷取目前的整合區域。如要瞭解支援的基本函式，請參閱「 支援的基本函式」。

      • 按一下 [儲存]。
   3. 在「輸入」列中，按一下任何輸入變數、值或基本函式上的「+ (新增函式)」，即可從可用對應函式清單中新增對應函式。對應函式可以有一或多個參數。每個參數可以有值、變數或基本函式，後方接著一連串的對應函式。
      • 如要新增巢狀函式，請按一下函式參數旁邊的「+」(新增函式)。同樣地，如要移除或刪除最近新增的函式，請按一下「- (刪除上一個函式)」。
      • 如要在對應運算式之間新增、移除或變更函式，請按一下函式，然後從下拉式選單中分別選取「新增函式」、「移除函式」或「變更函式」。

      如要進一步瞭解對應函式，請參閱對應函式。

      如要瞭解支援的對應函式，請參閱「 支援的資料類型和對應函式」。

      • 如要移除對應運算式中的變數，請按一下變數列旁的「移除」。
      • 如要移除整個「輸入」列，請按一下該列的 「清除」。
3. 設定對應 Output：
   Output：資料對應輸出的目標變數。目標變數可用於後續輸入列的對應。
   1. 將「變數」清單中的變數拖曳至「輸出」列。如果沒有可用的變數，請按一下「建立新變數」，設定新變數的名稱和資料類型。(選用) 您可以按一下輸出變數，然後選取是否要將該變數做為整合作業的輸出，或是做為另一個整合作業的輸入。
   2. 如要移除輸出變數，請按一下 「清除」。
4. (選用) 如要刪除對應資料列，請按一下 「刪除這項對應」。
5. 對應完成後，請關閉「資料對應編輯器」。系統會自動儲存所有變更。

完成的資料對應會顯示在「資料對應」工作設定窗格中，如下圖所示：

支援的資料類型和對應函式

在「資料對應」工作，Application Integration 支援下列變數資料類型：

• 字串和字串陣列
• 整數和整數陣列
• Double 和 Double 陣列
• 布林值和布林值陣列
• JSON

下表列出各資料類型可用的資料對應函式。

資料類型	支援的對應函式
布林值	AND, EQUALS, NAND, NOR, NOT, OR, TO_JSON, TO_STRING, XNOR, XOR
布林值陣列	APPEND, APPEND_ALL, CONTAINS, FILTER, FOR_EACH, GET, REMOVE, REMOVE_AT, SET, SIZE, TO_JSON, TO_SET
雙精度值	ADD、 DIVIDE、 CEIL、 EQUALS、 EXPONENT、 GREATER_THAN、 GREATER_THAN_EQUAL_TO、 FLOOR、 LESS_THAN、 LESS_THAN_EQUAL_TO、 MOD、 MULTIPLY、 ROUND、 SUBTRACT、 TO_JSON、 TO_STRING
雙陣列	APPEND、 APPEND_ALL、 AVG、 CONTAINS、 FILTER、 FOR_EACH、 GET、 MAX、 MIN、 REMOVE、 REMOVE_AT、 SET、 SIZE、 SUM、 TO_JSON、 TO_SET
整數	ADD、 DIVIDE、 EPOCH_TO_HUMAN_READABLE_TIME、 EQUALS、 EXPONENT、 GREATER_THAN、 GREATER_THAN_EQUAL_TO、 LESS_THAN、 LESS_THAN_EQUAL_TO、 MOD、 MULTIPLY、 SUBTRACT、 TO_DOUBLE、 TO_JSON、 TO_STRING
整數陣列	APPEND、 APPEND_ALL、 AVG、 CONTAINS、 FILTER、 FOR_EACH、 GET、 MAX、 MIN、 REMOVE、 REMOVE_AT、 SET、 SIZE、 SUM、 TO_JSON、 TO_SET
JSON	APPEND_ELEMENT、 FLATTEN、 FILTER、 FOR_EACH、 GET_ELEMENT、 GET_PROPERTY、 MERGE、 REMOVE_PROPERTY、 RESOLVE_TEMPLATE、 SET_PROPERTY、 SIZE、 TO_BOOLEAN、 TO_BOOLEAN_ARRAY、 TO_DOUBLE、 TO_DOUBLE_ARRAY、 TO_INT、 TO_INT_ARRAY、 TO_STRING、 TO_STRING_ARRAY
字串	CONCAT、 CONTAINS、 DECODE_BASE64_STRING、 EQUALS、 EQUALS_IGNORE_CASE、 LENGTH、 REPLACE_ALL、 RESOLVE_TEMPLATE、 SPLIT、 SUBSTRING、 TO_BASE_64、 TO_BOOLEAN、 TO_DOUBLE、 TO_INT、 TO_JSON、 TO_LOWERCASE、 TO_UPPERCASE
字串陣列	APPEND、 APPEND_ALL、 CONTAINS、 FILTER、 FOR_EACH、 GET、 REMOVE、 REMOVE_AT、 SET、 SIZE、 TO_JSON、 TO_SET

如要進一步瞭解各個資料對應函式，請參閱資料對應函式參考資料。

支援的基本函式

下表列出可用的資料對應基本函式：

資料類型	支援的基本函式
整數	NOW_IN_MILLIS
整數陣列	INT_LIST
字串	GENERATE_UUID, GET_EXECUTION_ID, GET_INTEGRATION_NAME, GET_INTEGRATION_REGION, GET_PROJECT_ID

如要進一步瞭解各個資料對應基本函式，請參閱資料對應函式參考資料。

最佳做法

使用「資料對應」工作，可有效轉換重要變數並傳遞至整合流程中的各項工作。建構整合服務時，請注意以下幾點：

• 系統會依序執行對應作業，由上而下。也就是說，如果輸入變數 A 對應至第一列的輸出變數 B，則變數 B 可用於後續列的對應。
• 在每個資料列中，「輸入」資料列的資料類型必須與「輸出」資料列的資料類型相符。 如要在類型之間轉換，請使用 TO_STRING 和 TO_INT 等轉換函式。
• 轉換鏈結的長度沒有限制。不過，對大型鏈結轉換進行偵錯可能很困難。建議您讓輸入轉換保持可讀性，並將複雜的轉換作業拆分成多個對應。
• 如果對應關係需要備用值，請為該對應關係設定備用值。如果未提供備用值，當輸入值或轉換作業傳回 null 時，對應會傳回錯誤。
• 刪除變數時，請務必刪除包含該變數的所有對應。

如要瞭解資料對應工作適用的用量限制，請參閱「 用量限制」。

注意事項

如果是 JSON 變數，Application Integration 會根據 JSON 結構定義，在下列情況下將變數的子項屬性解讀為 JSON 類型：

• 如果子項屬性的型別指定空值，例如：

  {
    "properties": {
      "PersonID": {
        "type": [
          "double",
          "null"
        ],
        "readOnly": false
      }
    }
  }

• 如果子項屬性的類型指定多個資料類型，例如：

  {
    "properties": {
      "PersonID": {
        "type": [
          "integer",
          "string",
          "number"
        ],
        "readOnly": false
      }
    }
  }

在這些情況下，您必須使用資料對應函式，將子項變數明確轉換為所需類型。

下列範例說明各種屬性宣告類型，並展示如何使用資料對應函式取得所需類型：

範例 1

{
  "type": "object",
  "properties": {
    "dbIntegers": {
      "type": "array",
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "dbBooleans": {
      "type": [
        "array"
      ],
      "items": {
        "type": "boolean"
      }
    }
  }
}

應用程式整合會將 dbIntegers 解讀為 JSON 類型，並將 dbBooleans 解讀為 BOOLEAN_ARRAY 類型。

如要轉換 dbIntegers，請使用：

dbIntegers.TO_INT_ARRAY()

範例 2

{
  "type": "object",
  "properties": {
    "dbId": {
      "type": [
        "number",
        "null"
      ],
      "readOnly": false
    },
    "dbStatus": {
      "type": [
        "boolean",
        "null"
      ],
      "readOnly": false
    }
  }
}

應用程式整合會將 dbId 和 dbStatus 視為 JSON 類型，但 dbId 是可接受單一雙精度浮點值或空值的參數，而 dbStatus 是可接受單一布林值或空值的參數。

如要轉換 dbId 和 dbStatus，請使用：

dbId.TO_DOUBLE()

dbStatus.TO_BOOLEAN()

範例 3

{
  "type": "object",
  "properties": {
    "dbString": {
      "type": [
        "string"
      ],
      "readOnly": false
    }
  }
}

Application Integration 會將 dbString 視為字串類型。

錯誤處理策略

工作錯誤處理策略會指定工作因暫時性錯誤而失敗時，系統應採取的動作。如要瞭解如何使用錯誤處理策略，以及不同類型的錯誤處理策略，請參閱「錯誤處理策略」。

配額與限制

如要瞭解配額和限制，請參閱「配額與限制」。

後續步驟

• 瞭解所有工作和觸發條件。
• 瞭解資料對應工作函式
• 瞭解如何測試及發布整合項目。
• 瞭解如何 處理錯誤。
• 瞭解整合執行記錄。