使用 Azure Data Factory 從 REST 端點複製並轉換資料

適用於： Azure Data Factory Azure Synapse Analytics

本文說明如何在 Azure Data Factory 中使用複製活動（Copy Activity）來從 REST 端點複製資料。 本文基於Azure Data Factory 中的 Copy Activity，該文對 Copy Activity 提供了一般概述。

此 REST 連接器、 HTTP 連接器與 Web 表格連接器 之間的差異有：

• REST 連接器 特別支援從 RESTful API 複製數據。
• HTTP 連接器 是通用的，用於從任何 HTTP 端點擷取資料，例如下載檔案。 在這個 REST 連接器之前，你可以用 HTTP 連接器來從 RESTful API 複製資料，雖然支援但功能不如 REST 連接器。
• Web 數據表連接器 會從 HTML 網頁擷取數據表內容。

支援的功能

下列功能支援此 REST 連接器：

（1） Azure 整合執行時 （2） 自架整合執行時

如需支援作為來源/接收的數據存放區清單，請參閱 支持的數據存放區。

具體而言，此泛型 REST 連接器支援：

• 從 REST 端點使用 GET 或 POST 方法複製資料，並使用 POST、PUT 或 PATCH 方法將資料複製至 REST 端點。
• 透過以下認證之一複製資料： 匿名認證、 Basic認證、 服務主體認證、 OAuth2 用戶端憑證、 系統指定管理身份及 使用者指定管理身份。
• REST API 中的分頁。
• 針對 REST 作為來源，複製 REST JSON 回應 as-is 或使用 架構對應加以剖析。 僅支援 JSON 格式的回應承載。

先決條件

如果你的資料儲存位於本地網路、Azure虛擬網路或亞馬遜虛擬私人雲中，你需要配置一個自架整合執行時來連接它。

如果你的資料儲存是雲端管理型資料服務，你可以使用Azure Integration Runtime。 如果存取權限限制在防火牆規則中核准的 IP，你可以將 Azure Integration Runtime IPs 加入允許清單。

你也可以在 Azure Data Factory 中使用 managed 虛擬網路整合執行時功能，無需安裝和設定自架整合執行環境即可存取本地網路。

如需 Data Factory 所支援之網路安全性機制和選項的詳細資訊，請參閱 數據存取策略。

開始

若要透過管線執行複製活動，您可以使用下列其中一個工具或 SDK：

• 複製資料工具
• Azure portal
• .NET SDK
• Python SDK
• Azure PowerShell
• REST API
• Azure Resource Manager 模板

使用 UI 建立 REST 連結服務

請依照以下步驟在 Azure 入口網站介面中建立一個 REST 連結服務。

1. 請瀏覽 Azure Data Factory 或 Synapse 工作區的「管理」標籤，選擇「連結服務」，然後選擇「新建服務」：

   • Azure Data Factory
   • Azure Synapse

   

2. 搜尋 REST 並選取 REST 連接器。

   

3. 設定服務詳細資料，測試連線，然後建立新的連結服務。

   

連接器設定詳細資料

下列各節提供屬性的相關詳細資料，您可使用這些屬性來定義 REST 連接器專屬的 Data Factory 實體。

連結服務屬性

以下是針對 REST 連結服務支援的屬性：

如需不同的驗證類型，請參閱對應的各章節以進一步了解詳細資料。

• 基本身份驗證
• 服務主體帳戶驗證
• OAuth2 用戶端憑證認證
• 系統指派的受控識別驗證
• 使用者指派的受控識別驗證
• 匿名驗證

使用基本驗證

將 authenticationType 屬性設定為 Basic。 除了上一節所述的一般屬性以外，請指定下列屬性：

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<REST endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

使用服務主體驗證

將 authenticationType 屬性設定為 AadServicePrincipal。 除了上一節所述的一般屬性以外，請指定下列屬性：

範例 1：使用服務主體金鑰驗證

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalKey": {
                "value": "<service principal key>",
                "type": "SecureString"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

範例 2：使用服務主體憑證驗證

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": {
                "type": "SecureString",
                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
            },
            "servicePrincipalEmbeddedCertPassword": {
                "type": "SecureString",
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

將服務主體證書儲存在 Azure 金鑰保存庫中

你有兩個選項可以將服務主體憑證儲存在 Azure Key Vault：

• 選項1

  1. 將服務主體憑證轉換為 base64 字串。 請從 本文深入瞭解。

  2. 在 Azure Key Vault 裡把 base64 字串存為秘密。

     

     

• 選項 2

  如果你無法從 Azure Key Vault 下載憑證，可以使用這個 template，將轉換後的服務主體憑證存為 Azure Key Vault 的秘密。

  

使用 OAuth2 用戶端憑證驗證

將 authenticationType 屬性設定為 OAuth2ClientCredential。 除了上一節所述的一般屬性以外，請指定下列屬性：

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "enableServerCertificateValidation": true,
            "authenticationType": "OAuth2ClientCredential",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "tokenEndpoint": "<token endpoint>",
            "scope": "<scope>",
            "resource": "<resource>"
        }
    }
}

使用系統指派的受控識別驗證

將 authenticationType 屬性設定為 ManagedServiceIdentity。 除了上一節所述的一般屬性以外，請指定下列屬性：

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

使用使用者指派的受控識別驗證

將 authenticationType 屬性設定為 ManagedServiceIdentity。 除了上一節所述的一般屬性以外，請指定下列屬性：

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }    
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

使用驗證標頭

此外，您可以設定驗證的要求標頭，以及內建驗證類型。

範例：使用 API 金鑰驗證

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint>",
            "authenticationType": "Anonymous",
            "authHeaders": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

資料集屬性

本節提供 REST 資料集所支援的屬性清單。

如需可用來定義資料集的完整區段和屬性清單，請參閱 數據集和鏈接服務。

若要從 REST 複製資料，以下是支援的屬性：

如果你在資料集中設定 requestMethod、 additionalHeaders、 requestBody， paginationRules 複製操作仍支援 as-is，但你應該在活動中使用新模型。

例：

{
    "name": "RESTDataset",
    "properties": {
        "type": "RestResource",
        "typeProperties": {
            "relativeUrl": "<relative url>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<REST linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

複製活動屬性

本節提供 REST 來源和接收器支援的屬性清單。

如需可用來定義活動的區段和屬性完整清單，請參閱 管線。

REST 作為來源

複製活動 來源 區段中支援下列屬性：

範例 1：搭配分頁使用 Get 方法

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "additionalHeaders": {
                    "x-user-defined": "helloworld"
                },
                "paginationRules": {
                    "AbsoluteUrl": "$.paging.next"
                },
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

範例 2：使用 Post 方法

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "requestMethod": "Post",
                "requestBody": "<body for POST REST request>",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

REST 作為接收器

複製活動的 sink 區段支援下列屬性：

當作接收器的 REST 連接器可搭配接受 JSON 的 REST API 使用。 資料以 JSON 格式傳送，模式如下。 視需要，使用複製活動 結構映射 來重新調整來源資料，使其符合 REST API 預期的有效載荷。

[
    { <data object> },
    { <data object> },
    ...
]

例：

"activities":[
    {
        "name": "CopyToREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<REST output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "RestSink",
                "requestMethod": "POST",
                "httpRequestTimeout": "00:01:40",
                "requestInterval": 10,
                "writeBatchSize": 10000,
                "httpCompressionType": "none",
            },
        }
    }
]

對應資料流程屬性

整合資料集和內嵌資料集的資料流程都支援 REST。

來源轉換

接收轉換

您可以設定刪除、插入、更新和 upsert 方法，以及針對 CRUD 作業傳送至 REST 接收器的相對資料列資料。

範例資料流程指令碼

注意在匯項前使用了 alter 列轉換，指示 Data Factory 對 REST 匯項採取何種動作。 這個動作可以是插入、更新、更新或刪除。

AlterRow1 sink(allowSchemaDrift: true,
	validateSchema: false,
	deletable:true,
	insertable:true,
	updateable:true,
	upsertable:true,
	rowRelativeUrl: 'periods',
	insertHttpMethod: 'PUT',
	deleteHttpMethod: 'DELETE',
	upsertHttpMethod: 'PUT',
	updateHttpMethod: 'PATCH',
	timeout: 30,
	requestFormat: ['type' -> 'json'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> sink1

分頁支援

當你從 REST API 複製資料時，REST API 通常會將單一請求的回應有效載荷大小限制在合理範圍內。 為了回傳大量資料，它會將結果拆分成多個頁面，並要求呼叫者連續發送請求以取得下一頁結果。 通常，單頁的請求是動態的，並由前一頁回應中回傳的資訊組成。

此泛型 REST 連接器支援下列分頁模式：

• 下一個要求的絕對或相對 URL = 目前回應本文中的屬性值
• 下一個要求的絕對或相對 URL = 目前回應標頭中的標頭值
• 下一個要求的查詢參數 = 目前回應本文中的屬性值
• 下一個要求的查詢參數 = 目前回應標頭中的標頭值
• 下一個要求的標頭 = 目前回應本文中的屬性值
• 下一個要求的標頭 = 目前回應標頭中的標頭值

分頁規則 定義為資料集中的字典，包含一個或多個大小寫區分的鍵值對。 此設定用於從第二頁開始產生請求。 當連接器收到 HTTP 狀態碼 204（無內容）或任何 JSONPath 表達式回 paginationRules 傳 null 時，就會停止迭代。

分頁規則中支援的鍵值：

分頁規則中支援的值：

分頁規則範例

本節提供分頁規則設定的範例清單。

範例 1：QueryParameters 中的變數

此範例提供設定步驟，傳送變數位於 QueryParameters 中的多個要求。

多個要求：

baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0,
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
...... 
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=10000

步驟 1：在 [基底 URL]sysparm_offset={offset} 或 [相對 URL] 中輸入 ，如下列螢幕擷取畫面所示：

或

步驟 2：將 分頁規則 設為選項 1 或選項 2：

• Option1： “QueryParameters.{offset}“ ： ”RANGE：0：10000：1000”

• Option2： “AbsoluteUrl.{offset}“ ： ”RANGE：0：10000：1000”

範例 2：AbsoluteUrl 中的變數

此範例提供設定步驟，傳送變數位於 AbsoluteUrl 中的多個要求。

多個要求：

BaseUrl/api/now/table/t1
BaseUrl/api/now/table/t2
...... 
BaseUrl/api/now/table/t100

步驟 1：在連結服務設定頁面的[基底 URL]{id} 或資料集連線窗格的 [相對 URL] 中輸入 。

或

步驟 2：將分頁規則設定為 “AbsoluteUrl.{id}“ ：”RANGE：1：100：1”。

範例 3：標頭中的變數

此範例提供設定步驟，傳送變數位於 Headers 中的多個要求。

多個要求：

RequestUrl: https://example/table
Request 1: Header(id->0)
Request 2: Header(id->10)
......
Request 100: Header(id->100)

步驟 1：在 [其他標頭]{id} 中輸入 。

步驟 2：將分頁規則設定為 “Headers.{id}“ ： ”RANGE：0：100：10”。

範例 4：變數在 AbsoluteUrl/QueryParameters/Headers，結尾變數未預先定義，且結束條件是基於回應

此範例提供設定步驟，以傳送多個要求，其變數位於 AbsoluteUrl/QueryParameters/Headers 中，但未定義結束變數。 針對不同回應，範例 4.1-4.6 說明不同結束條件規則設定。

多個要求：

Request 1: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0, 
Request 2: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
Request 3: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=2000,
...... 

此範例中會遇到兩種回應：

回應一：

{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ]
}

回應二：

{
    Data: [
        {key1: val5, key2: val6
        },
        {key1: val7, key2: val8
        }
    ]
}

步驟 1：將分頁規則的範圍設定為範例 1，並將範圍的結尾保留為 “AbsoluteUrl.{offset}“： ”RANGE：0：：1000”。

步驟 2：根據不同的最後一個回應，設定不同結束條件規則。 請參閱下列範例：

• 範例 4.1：分頁會在回應中特定節點的值空白時結束

  REST API 會以下列結構傳回最後一個回應：

  {
      Data: []
  }
  

  將結束條件規則設定為 「EndCondition：$.data」： “Empty” ，以在回應中特定節點的值是空的時結束分頁。

  

• 範例 4.2：當回應中特定節點的值不存在時，分頁結束

  REST API 會以下列結構傳回最後一個回應：

  {}
  

  將結束條件規則設定為 「EndCondition：$.data」： “NonExist”， 以在回應中特定節點的值不存在時結束分頁。

  

• 範例 4.3：分頁會在回應中特定節點的值存在時結束

  REST API 會以下列結構傳回最後一個回應：

  {
      Data: [
          {key1: val991, key2: val992
          },
          {key1: val993, key2: val994
          }
      ],
              Complete: true
  }
  

  將結束條件規則設定為 "EndCondition:$.Complete": "Exist"，以在回應中特定節點的值存在時結束分頁處理。

  

• 範例 4.4：分頁會在回應中特定節點的值是用戶定義的 const 值時結束

  REST API 會以下列結構傳回回應：

  {
      Data: [
          {key1: val1, key2: val2
          },
          {key1: val3, key2: val4
          }
      ],
              Complete: false
  }
  

  ......

  且最後一個回應為下列結構：

  {
      Data: [
          {key1: val991, key2: val992
          },
          {key1: val993, key2: val994
          }
      ],
              Complete: true
  }
  

  將結束條件規則設定為 「EndCondition：$。Complete“： ”Const：true“ 會在回應中特定節點的值是使用者定義的 const 值時結束分頁。

  

• 範例 4.5：當回應中的標頭鍵值等於使用者定義的 const 值時，分頁結束

  REST API 回應中的標頭索引鍵如下列結構所示：

  回應標頭 1：header(Complete->0)
  ......
  最後一個回應標頭：header(Complete->1)
  

  將結束條件規則設為 「EndCondition：headers.完成“：「Const：1」 ，當回應的標頭鍵值等於使用者定義的 const 值時，結束分頁。

  

• 範例 4.6：分頁會在響應標頭中的索引鍵存在時結束

  REST API 回應中的標頭索引鍵如下列結構所示：

  回應標頭 1：header()
  ......
  最後一個回應標頭：header(CompleteTime->20220920)
  

  將結束條件規則設定為 "EndCondition:headers.CompleteTime": "Exist"，以在響應標頭中存在該鍵時結束分頁。

  

範例 5：設定終端條件以避免在未定義範圍規則時無限請求

本範例提供設定步驟，以在未使用範圍規則時傳送多個要求。 您可以設定結束條件，參考範例 4.1-4.6，以避免無止盡的要求。 REST API 會傳回下列結構的回應，在此情況下，下一頁的 URL 會以 paging.next 表示。

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}
...

最後一個回應為：

{
    "data": [],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "Same with Last Request URL"
    }
}

步驟 1：將分頁規則設定為 “AbsoluteUrl”：“$.paging.next”。

步驟二：如果 next 最後一個回應的 URL 總是和最後一個請求的 URL 相同且不是空的，程序就會發送無限請求。 使用終結條件來避免無止盡的請求。 因此，請參考範例 4.1 至 4.6 來設定終點條件規則。

範例 6：設定最大請求數以避免無限請求

設定 MaxRequestNumber 以避免無休止的要求，如下列螢幕快照所示：

範例 7：RFC 5988 分頁規則預設支援

後端會根據標頭中的 RFC 5988 樣式連結自動取得下一個 URL。

範例 8a：在對應資料流程中使用分頁時，下一個要求 URL 位於回應主體中

此範例說明下一個要求 URL 來自回應本文時，如何設定對應資料流中的分頁規則和結束條件規則。

回應結構描述如下所示︰

分頁規則應設定為以下螢幕擷取畫面：

預設情況下，當 body.{@odata.nextLink} 為 空或為空時，分頁會停止。

但如果最後回應內容中的 @odata.nextLink 值等於最後一個請求網址，就會導致無止盡的循環。 若要避免此條件，請定義結束條件規則。

• 如果最後一個回應中的 Value 是 空的，則可以如下所示設定結束條件規則：

  

• 如果回應標頭中完整索引鍵的值等於 true，表示分頁結束，則可以將結束條件規則設定如下：

  螢幕快照顯示當回應標頭中的完成鍵等於 true 時，設置結束條件規則，以表示分頁的結尾。

範例 8b：在複製活動中使用分頁時，下一個要求 URL 位於回應主體中

此範例示範如何在當回應主體內包含下一個要求 URL 時，在複製活動中設定分頁規則。

回應結構描述如下所示︰

分頁規則應依下列螢幕擷取畫面所示進行設定：

範例 9：在對應資料流中使用分頁時，回應格式為 XML 且下一個要求 URL 來自回應本文

此範例說明回應格式為 XML 且下一個要求 URL 來自回應本文時，如何設定對應資料流中的分頁規則。 如以下截圖所示，第一個網址是 https://< user.dfs.core.windows.net/bugfix/test/movie_1.xml>

回應結構描述如下所示︰

分頁規則語法與範例 8 相同，且應在此範例中設定如下：

匯出 JSON 回應的原狀

您可以使用 REST 連接器，將 REST API 的 JSON 回應 as-is 匯出至各種檔案型記憶體系統（接收）。 要啟用這種與結構無關的複製行為，請使用預設的架構映射（不要在複製活動的映射標籤中定義任何映射）。

結構描述對應

若要將資料從 REST 端點複製到表格數據存放區，請參閱 架構對應。

相關內容

關於複製活動在Azure Data Factory中支援的資料來源與匯入資料庫清單，請參見 支援的資料儲存與格式。