使用 Azure Data Factory 或 Synapse Analytics 複製 OData 來源中的資料

發行項
08/01/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費啟動新的試用版！

本文概述如何使用 Azure Data Factory 或 Synapse Analytics 管線中的複製活動複製 OData 來源中的資料。本文是以複製活動為基礎，該文提供複製活動的一般概觀。

支援的功能

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

支援的功能	IR
複製活動 (來源/-)	① ②
查閱活動	① ②

① Azure 整合執行階段 ② 自我裝載整合執行階段

如需支援做為來源/接收器的資料存放區清單，請參閱支援的資料存放區。

具體而言，這個 OData 連接器支援：

OData 2.0、3.0 和 4.0 版。
使用下列其中一種驗證來複製資料：匿名、基本、Windows 和 Microsoft Entra 服務主體。

必要條件

如果您的資料存放區位於內部部署網路、Azure 虛擬網路或 Amazon 虛擬私人雲端中，則必須設定自我裝載整合執行階段以與其連線。

如果您的資料存放區是受控雲端資料服務，則可使用 Azure Integration Runtime。如果只能存取防火牆規則中核准的 IP，您可以將 Azure Integration Runtime IP 新增至允許清單。

您也可以使用 Azure Data Factory 中的受控虛擬網路整合執行階段功能來存取內部部署網路，而不需要安裝和設定自我裝載整合執行階段。

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

開始使用

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

使用 UI 建立 OData 存放區的連結服務

使用下列步驟，在 Azure 入口網站 UI 中建立連結至 OData 存放區的服務。

瀏覽至 Azure Data Factory 或 Synapse 工作區中的 [管理] 索引標籤，並選取 [連結服務]，然後選取 [新增]：
- Azure Data Factory
- Azure Synapse
搜尋 OData，並選取 OData 連接器。
設定服務詳細資料，測試連線，然後建立新的連結服務。

連接器設定詳細資料

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

連結服務屬性

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

屬性	描述	必要
type	type 屬性必須設為 OData。	Yes
URL	OData 服務的根 URL。	Yes
authenticationType	用來連線到 OData 來源的驗證類型。允許的值為 Anonymous、Basic、Windows 和 AadServicePrincipal。不支援使用者型 OAuth。您可以在 `authHeader` 屬性中額外設定驗證標頭。	Yes
authHeaders	用於驗證的其他 HTTP 要求標頭。例如，若要使用 API 金鑰驗證，您可以選取驗證類型 “Anonymous”，並在標頭中指定 API 金鑰。	No
userName	如果使用基本或 Windows 驗證，請指定 userName。	No
password	針對您指定 userName 的使用者帳戶指定 password。將此欄位標記為 SecureString 類型以將其安全地儲存。您也可以參考 Azure Key Vault 中儲存的認證。	No
servicePrincipalId	指定 Microsoft Entra 應用程式的用戶端識別碼。	No
aadServicePrincipalCredentialType	指定要用於服務主體驗證的認證類型。允許的值包為：`ServicePrincipalKey` 或 `ServicePrincipalCert`。	No
servicePrincipalKey	指定 Microsoft Entra 應用程式的金鑰。將此欄位標記為 SecureString 以將其安全地儲存，或參考 Azure Key Vault 中儲存的祕密。	No
servicePrincipalEmbeddedCert	指定在 Microsoft Entra ID 中所註冊應用程式的 base64 編碼憑證，並確定憑證內容類型為 PKCS #12。將此欄位標記為 SecureString 以將其安全地儲存，或參考 Azure Key Vault 中儲存的祕密。	No
servicePrincipalEmbeddedCertPassword	如果您的憑證受到密碼保護，則指定您憑證的密碼。將此欄位標記為 SecureString 以將其安全地儲存，或參考 Azure Key Vault 中儲存的祕密。	No
tenant	指定您的應用程式所在租用戶的資訊 (網域名稱或租用戶識別碼)。將滑鼠游標暫留在 Azure 入口網站右上角，即可擷取它。	No
aadResourceId	指定您要求授權的 Microsoft Entra 資源。	No
azureCloudType	針對服務主體驗證，請指定註冊 Microsoft Entra 應用程式的 Azure 雲端環境類型。允許的值為 AzurePublic、AzureChina、AzureUsGovernment 和 AzureGermany。預設會使用服務的雲端環境。	No
connectVia	用來連線到資料存放區的整合執行階段。從必要條件一節深入了解。如果未指定，則會使用預設的 Azure Integration Runtime。	No

範例 1：使用匿名驗證

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "https://services.odata.org/OData/OData.svc",
            "authenticationType": "Anonymous"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

範例 2：使用基本驗證

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

範例 3：使用 Windows 驗證

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "Windows",
            "userName": "<domain>\\<user>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "aadServicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<AAD resource URL>"
        }
    },
    "connectVia": {
        "referenceName": "<name of Integration Runtime>",
        "type": "IntegrationRuntimeReference"
    }
}

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

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "aadServicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": { 
                "type": "SecureString", 
                "value": "<base64 encoded string of (.pfx) certificate data>"
            },
            "servicePrincipalEmbeddedCertPassword": { 
                "type": "SecureString", 
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<AAD resource e.g. https://tenant.sharepoint.com>"
        }
    },
    "connectVia": {
        "referenceName": "<name of Integration Runtime>",
        "type": "IntegrationRuntimeReference"
    }
}

範例 6：使用 API 金鑰驗證

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "Anonymous",
            "authHeader": {
                "APIKey": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

資料集屬性

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

如需定義資料集的區段和屬性完整清單，請參閱資料集和連結服務。

若要從 OData 複製資料，請將資料集的 type 屬性設定為 ODataResource。以下是支援的屬性：

屬性	描述	必要
type	資料集的 type 屬性必須設定為 ODataResource。	Yes
path	OData 資源的路徑。	Yes

範例

{
    "name": "ODataDataset",
    "properties":
    {
        "type": "ODataResource",
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<OData linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties":
        {
            "path": "Products"
        }
    }
}

複製活動屬性

本節提供 OData 來源所支援的屬性清單。

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

OData 作為來源

若要從 OData 複製資料，複製活動「來源」區段中支援下列屬性：

屬性	描述	必要
type	複製活動來源的 type 屬性必須設定為 ODataSource。	Yes
query	用來篩選資料的 OData 查詢選項。範例：`"$select=Name,Description&$top=5"`。注意：OData 連接器會從以下的組合 URL 複製資料：`[URL specified in linked service]/[path specified in dataset]?[query specified in copy activity source]`。如需詳細資訊，請參閱 OData URL 元件。	No
httpRequestTimeout	用來取得回應的 HTTP 要求會有的逾時值 (TimeSpan 值)。此值是取得回應的逾時值，而非讀取回應資料的逾時值。如果未指定，則預設值是 00:30:00 (30 分鐘)。	No

範例

"activities":[
    {
        "name": "CopyFromOData",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<OData input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ODataSource",
                "query": "$select=Name,Description&$top=5"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

如果您使用 RelationalSource 具型別來源，雖然仍照現狀支援，但建議您往後使用新的版本。

OData 的資料類型對應

從 OData 複製資料時，會內部使用 OData 資料類型與服務內所使用過渡期資料類型之間的下列對應。若要了解複製活動如何將來源結構描述和資料類型對應至接收端，請參閱結構描述和資料類型對應。

OData 資料類型	過渡期服務資料類型
Edm.Binary	Byte[]
Edm.Boolean	Bool
Edm.Byte	Byte[]
Edm.DateTime	Datetime
Edm.Decimal	Decimal
Edm.Double	Double
Edm.Single	Single
Edm.Guid	GUID
Edm.Int16	Int16
Edm.Int32	Int32
Edm.Int64	Int64
Edm.SByte	Int16
Edm.String	String
Edm.Time	TimeSpan
Edm.DateTimeOffset	DateTimeOffset

注意

不支援 OData 複雜資料類型 (例如物件)。

從 Project Online 複製資料

Project Online 需要 Azure Data Factory 不支援的使用者型 OAuth。若要從 Project Online 複製資料，您可以使用 OData 連接器以及取自 Postman 這類工具的存取權杖。

警告

存取權杖預設會在 1 小時到期，您需要在到期時取得新的存取權杖。

使用 Postman 以取得存取權杖：

注意

Postman 由一些開發人員用於測試遠端 Web API。不過，有一些與其使用方式相關聯的安全性和隱私權風險。本文不認可將 Postman 用於生產環境。請自行承擔其使用風險。
1. 導覽至 Postman 網站上的 [授權] 索引標籤。
2. 在 [類型] 方塊中，選取 [OAuth 2.0]，然後在 [將授權資料新增至] 方塊中，選取 [要求標頭]。
3. 在 [設定新權杖] 頁面中填入下列資訊，以取得新的存取權杖：
  - 授與類型：選取 [授權碼]。
  - 回呼 URL：輸入 https://www.localhost.com/。
  - 驗證 URL：輸入 https://login.microsoftonline.com/common/oauth2/authorize?resource=https://<your tenant name>.sharepoint.com。將 <your tenant name> 取代為您自己的租用戶名稱。
  - 存取權杖 URL：輸入 https://login.microsoftonline.com/common/oauth2/token。
  - 用戶端識別碼：輸入您的 Microsoft Entra 服務主體識別碼。
  - 用戶端祕密：輸入您的服務主體祕密。
  - 用戶端驗證：選取 [傳送為基本驗證標頭]。
4. 系統會要求您使用您的使用者名稱和密碼登入。
5. 在您取得存取權杖之後，請進行複製並儲存，以供下一個步驟使用。
建立 OData 連結服務：
- 服務 URL：輸入 https://<your tenant name>.sharepoint.com/sites/pwa/_api/Projectdata。將 <your tenant name> 取代為您自己的租用戶名稱。
- 驗證類型：選取 [匿名]。
- 授權標頭：
  - 屬性名稱：選擇 [授權]。
  - 值：輸入 Bearer <access token from step 1>。
- 測試連結服務。
建立 OData 資料集：
1. 使用步驟 2 中所建立的 OData 連結服務來建立資料集。
2. 預覽資料。

查閱活動屬性

若要了解屬性的詳細資料，請參閱查閱活動。

如需複製活動作為來源和接收端支援的資料存放區清單，請參閱支援的資料存放區和格式。

共用方式為

使用 Azure Data Factory 或 Synapse Analytics 複製 OData 來源中的資料

支援的功能

必要條件

開始使用

使用 UI 建立 OData 存放區的連結服務

連接器設定詳細資料

連結服務屬性

資料集屬性

複製活動屬性

OData 作為來源

OData 的資料類型對應

從 Project Online 複製資料

查閱活動屬性

意見反應

其他資源

共用方式為

使用 Azure Data Factory 或 Synapse Analytics 複製 OData 來源中的資料

支援的功能

必要條件

開始使用

使用 UI 建立 OData 存放區的連結服務

連接器設定詳細資料

連結服務屬性

資料集屬性

複製活動屬性

OData 作為來源

OData 的資料類型對應

從 Project Online 複製資料

查閱活動屬性

相關內容

意見反應

其他資源