使用 Azure Data Factory 或 Synapse Analytics 從 Google Cloud Storage 複製資料

適用於： Azure Data Factory Azure Synapse Analytics

秘訣

Data Factory in Microsoft Fabric 是下一代的 Azure Data Factory，擁有更簡單的架構、內建 AI 及新功能。 如果你是資料整合新手，建議先從 Fabric Data Factory 開始。 現有的 ADF 工作負載可升級至 Fabric，以存取資料科學、即時分析與報告等新能力。

本文概述如何從 Google Cloud Storage (GCS) 複製資料。 欲了解更多，請閱讀 Azure Data Factory 及 Synapse Analytics 的入門文章。

支援的功能

此 Google 雲端儲存空間連接器支援下列功能：

支援的功能 IR
複製作業（來源/-） （1）（2）
映射資料流程 (來源/-) 1
查詢活動 （1）（2）
GetMetadata 活動 （1）（2）
刪除活動 （1）（2）

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

具體而言，此 Google Cloud Storage 連接器支援依原樣複製檔案，或使用支援的檔案格式和壓縮轉碼器來剖析檔案。 它利用 GCS 的 S3 相容互通性。

必要條件

您的 Google Cloud Storage 帳戶需要下列設定：

  1. 啟用 Google Cloud Storage 帳戶的互通性
  2. 設定預設專案，其中包含您要從目標 GCS 貯體複製的資料。
  3. 建立服務帳戶，並使用 GCP 上的雲端 IAM 定義正確的權限層級。
  4. 產生此服務帳戶的存取金鑰。

取得 Google Cloud Storage 的存取金鑰

所需的權限

若要從 Google Cloud Storage 複製資料，請確定您已獲得下列物件作業的權限︰ storage.objects.get 和 storage.objects.list。

如果您使用 UI 進行撰寫，則需要有 storage.buckets.list 權限，才能執行操作，例如測試連線至連線服務和從根目錄進行瀏覽。 如果您不想授與此權限，可以從 UI 選擇 [測試檔案路徑的連線] 或 [從指定的路徑瀏覽] 選項。

如需 Google Cloud Storage 角色和相關權限的完整清單，請參閱 Google Cloud 網站上的 Cloud Storage 的 IAM 角色 (英文)。

開始使用

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

使用 UI 建立連結至 Google Cloud Storage 的服務

請依照以下步驟在 Azure 入口網站介面中建立連結至 Google Cloud Storage 的服務。

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

  2. 搜尋 Google，然後選取 Google Cloud Storage (S3 API) 連接器。

    選取 Google Cloud Storage (S3 API) 連接器。

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

    設定連結至 Google Cloud Storage 的服務。

連接器設定詳細資料

下列各節提供屬性的相關詳細資料，這些屬性是用來定義 Google Cloud Storage 專屬的 Data Factory 實體。

連結服務屬性

以下是針對 Google Cloud Storage 連結服務支援的屬性：

屬性 描述 必要
型別 類型屬性必須設為 GoogleCloudStorage。 Yes
accessKeyId 密碼存取金鑰的識別碼。 若要尋找存取金鑰和秘密，請參閱必要條件。 Yes
secretAccessKey 密碼存取金鑰本身。 將此欄位標記為 SecureString 以安全地儲存，或指向儲存在 Azure Key Vault 中的秘密。 Yes
服務網址 將自訂 GCS 端點指定為 https://storage.googleapis.com。 Yes
connectVia 用來連線到資料存放區的 Integration Runtime。 你可以使用 Azure 整合執行環境，或是自架整合執行環境（如果你的資料儲存在私有網路中）。 如果沒有指定這個屬性，服務會使用預設的 Azure 整合執行時。 No

以下是範例：

{
    "name": "GoogleCloudStorageLinkedService",
    "properties": {
        "type": "GoogleCloudStorage",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            },
            "serviceUrl": "https://storage.googleapis.com"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

資料集屬性

Azure Data Factory 支援以下檔案格式。 請參閱每篇文章，以取得以格式為基礎的設定。

在以格式為基礎的資料集內 location 設定下，Google Cloud Storage 支援下列屬性：

屬性 描述 必要
型別 資料集中 下的 location 屬性必須設定為 GoogleCloudStorageLocation。 Yes
bucketName GCS 貯體名稱。 Yes
資料夾路徑 指定儲存區下的資料夾路徑。 若要使用萬用字元來篩選資料夾，則請跳過此設定，並在活動來源設定中指定。 No
檔案名稱 所指定儲存桶和資料夾路徑下的檔案名稱。 如果您想要使用萬用字元來篩選檔案，則請略過此設定，並在活動來源設定中予以指定。 No

範例：

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Google Cloud Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "GoogleCloudStorageLocation",
                "bucketName": "bucketname",
                "folderPath": "folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

複製活動屬性

如需可用來定義活動的區段和屬性完整清單，請參閱管線一文。 本節提供 Google Cloud Storage 來源所支援的屬性清單。

以 Google Cloud Storage 為來源類型

Azure Data Factory 支援以下檔案格式。 請參閱每篇文章，以取得以格式為基礎的設定。

在以格式為基礎的複製來源的 storeSettings 設定下，Google Cloud Storage 支援下列屬性：

屬性 描述 必要
型別 下的storeSettings屬性必須設定為GoogleCloudStorageReadSettings。 Yes
找到要複製的檔案：
選項 1：靜態路徑
 從資料集中指定的儲存桶或資料夾或檔案路徑進行複製。 如果您想要複製貯體或資料夾中的所有檔案，則請另外將 wildcardFileName 指定為 *。
選項 2：GCS 字首
- 前置詞		 在資料集中於指定貯體下設定的 GCS 索引鍵名稱首碼，用來篩選來源 GCS 檔案。 已選取名稱開頭為 bucket_in_dataset/this_prefix 的 GCS 金鑰。 其利用 GCS 的服務端篩選，提供比萬用字元篩選更好的效能。 No
選項 3：萬用字元
- 通配符資料夾路徑		 在資料集中於指定貯體下設定、含萬用字元的資料夾路徑，用來篩選來源資料夾。
允許的萬用字元為：* (符合零或多個字元) 和 ? (符合零或單一字元)。 如果資料夾名稱中包含萬用字元或逸出字元，請使用^來進行逸出。
如需更多範例，請參閱資料夾和檔案篩選範例。		 No
選項 3：萬用字元
- 通配符檔案名稱		 在指定貯體與資料夾路徑 (或萬用字元資料夾路徑) 下、含萬用字元的檔案名稱，用來篩選來源檔案。
允許的萬用字元為：* (符合零或多個字元) 和 ? (符合零或單一字元)。 若檔案名稱中有萬用字元或逸出字元，請用^來避開。 如需更多範例，請參閱資料夾和檔案篩選範例。		 Yes
選項 3：檔案清單
- 檔案清單路徑		 表示要複製指定的檔案集。 請指定一個包含希望複製的檔案清單的文字檔，每行一個檔案，該檔案的路徑為資料集中設定的相對路徑。
當您使用此選項時，請勿在資料集中指定檔案名稱。 檔案清單範例有更多範例可供參閱。		 No
其他設定：
遞迴 指出是否從子資料夾、或只有從指定的資料夾，以遞迴方式讀取資料。 請注意，當遞迴設為 true 且接收器是檔案型存放區時，不會在接收器上複製或建立空的資料夾或子資料夾。
允許的值為 true (預設值) 和 false。
設定 fileListPath 時，此屬性不適用。		 No
deleteFilesAfterCompletion（完成後刪除文件） 指出成功移至目的地存放區之後，是否要從來源存放區中刪除二進位檔案。 檔案刪除是按檔案進行的，因此當複製活動失敗時，您會看到某些檔案已複製到目的地並從來源刪除，而其他檔案仍保留在來源存放區中。
此屬性僅適用於二進位檔案複製案例。 預設值：false。		 No
modifiedDatetimeStart 檔案是根據「上次修改時間」屬性進行篩選。
若檔案的上次修改時間大於或等於 modifiedDatetimeStart 且小於 modifiedDatetimeEnd，則會選取檔案。 此時間會以 "2018-12-01T05:00:00Z" 格式套用至 UTC 時區。
屬性可以是 NULL，這表示將不會在資料集中套用任何檔案屬性篩選。 若 modifiedDatetimeStart 有日期時間值，但 modifiedDatetimeEnd 為 NULL，則將會選取上次修改時間屬性大於或等於該日期時間值的檔案。 若 modifiedDatetimeEnd 有日期時間值，但 modifiedDatetimeStart 為 NULL，則將會選取上次修改時間屬性小於該日期時間值的檔案。
設定 fileListPath 時，此屬性不適用。		 No
modifiedDatetimeEnd 同上。 No
enablePartitionDiscovery 對於分割的檔案，請指定是否要從檔案路徑剖析分割區，並將它們新增為更多來源資料行。
允許的值為 false (預設值) 和 true。		 No
partitionRootPath 啟用分割區探索時，請指定絕對根路徑，將已分割的資料夾當成資料行進行讀取。

如果未指定，則預設為
- 當您使用資料集中的檔案路徑或來源上的檔案清單時，分割區根路徑是資料集中所設定的路徑。
- 當您使用萬用字元資料夾篩選時，分割區根路徑是第一個萬用字元前面的子路徑。

例如，假設您將資料集中的路徑設定為 "root/folder/year=2020/month=08/day=27"：
- 如果您將分割區根路徑指定為 "root/folder/year=2020"，則除了檔案內的資料行之外，複製活動還會分別產生值為 "08" 和 "27" 的兩個資料行 month 和 day。
- 如果未指定分割區根路徑，則不會產生額外的資料行。		 No
最大並發連接數 (maxConcurrentConnections) 在活動執行期間建立至資料存放區的同時連線上限。 僅在想要限制並行連線時，才需要指定值。 No

範例：

"activities":[
    {
        "name": "CopyFromGoogleCloudStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "GoogleCloudStorageReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

資料夾和檔案篩選範例

本節描述含有萬用字元篩選之資料夾路徑和檔案名稱所產生的行為。

貯體 Key 遞迴 來源資料夾結構和篩選結果 (會擷取以粗體顯示的檔案)
貯體 Folder*/* 假 貯體
    FolderA
         File1.csv
         File2.json
        子資料夾1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
貯體 Folder*/* true 貯體
    FolderA
         File1.csv
         File2.json
        子資料夾1
             File3.csv
             File4.json
             File5.csv
    AnotherFolderB
        File6.csv
貯體 Folder*/*.csv 假 貯體
    FolderA
         File1.csv
        File2.json
        子資料夾1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
貯體 Folder*/*.csv true 貯體
    FolderA
         File1.csv
        File2.json
        子資料夾1
             File3.csv
            File4.json
             File5.csv
    AnotherFolderB
        File6.csv

檔案清單範例

本節說明在 Copy activity 原始碼中使用檔案清單路徑所產生的行為。

假設您的來源資料夾結構如下，且想要複製以粗體標示的檔案：

範例來源結構 FileListToCopy.txt 中的內容 組態
貯體
    FolderA
         File1.csv
        File2.json
        子資料夾1
             File3.csv
            File4.json
             File5.csv
    中繼資料
        檔案清單待複製.txt		 File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv		 在資料集中：
- 儲存桶：bucket
- 資料夾路徑：FolderA

複製活動來源中：
- 檔案清單路徑：bucket/Metadata/FileListToCopy.txt

檔案清單路徑指向相同資料存放區中的文字檔，其中包括要複製的檔案清單，每行一個檔案，且路徑是相對於資料集內設定的路徑。

映射資料流屬性

在對應資料流中轉換資料時，可以使用下列格式從 Google 雲端儲存空間讀取檔案：

格式特定設定位於該格式的文件中。 如需詳細資訊，請參閱對應資料流中的來源轉換。

來源轉換

在來源轉換中，您可讀取 Google 雲端儲存空間中的容器、資料夾或個別檔案。 使用 [來源選項] 索引標籤來管理檔案的讀取方式。

來源選項的螢幕擷取畫面。

萬用字元路徑：在單一來源轉換中，使用萬用字元模式會指示服務重複檢查每個相符的資料夾和檔案。 這在單一流程內處理多個檔案時很有效。 當您將滑鼠懸停在現有的萬用字元比對模式上時，會出現加號，透過此加號可新增多個萬用字元比對模式。

從來源容器中，選擇符合模式的一系列檔案。 在資料集內只能指定容器。 因此，萬用字元路徑也必須包含從根資料夾開始的資料夾路徑。

萬用字元範例：

  • * 代表任何一組字元。

  • ** 代表遞迴目錄巢狀。

  • ? 取代一個字元。

  • [] 比對括弧中的一或多個字元。

  • /data/sales/**/*.csv 取得 /data/sales 下的所有 .csv 檔案。

  • /data/sales/20??/**/ 取得 20 世紀的所有檔案。

  • /data/sales/*/*/*.csv 取得 /data/sales 下兩層的 csv 檔案。

  • /data/sales/2004/*/12/[XY]1?.csv 取得 2004 年 12 月、開頭為 X 或 Y 、且字首為兩位數的所有 .csv 檔案。

分割區根路徑：若檔案來源中有 key=value 格式 (如 year=2019) 的分割資料夾，則可將該分割區資料夾樹狀結構的最上層，指派給資料流程資料流中的資料行名稱。

首先，設定萬用字元來包含您要讀取的分割資料夾所有路徑，以及葉節點檔案。

分割區來源檔案設定的螢幕擷取畫面。

使用 [分割區根路徑] 設定來定義資料夾結構的最上層。 透過資料預覽來檢視資料的內容時，您會看到服務將新增在每個資料夾層級找到的已解析分割區。

分割區根路徑的螢幕擷取畫面。

檔案清單：這是檔案集。 建立文字檔，其中包含要處理的相對路徑檔案清單。 指向這個文字檔。

要儲存檔案名稱的資料行：將來源檔案的名稱儲存至資料中的資料行。 在此輸入新的資料行名稱以儲存檔案名稱字串。

完成後：選擇在資料流程後不操作來源檔案、刪除來源檔案，或移動來源檔案。 移動時的路徑是相對路徑。

若要在處理後將來源檔案移到另一個位置，請先選取 [移動] 當作檔案操作。 然後，設定「來源」目錄。 如果路徑中未使用任何萬用字元，則「來源」設定與來源資料夾相同。

若來源路徑包含萬用字元，則語法如下：

/data/sales/20??/**/*.csv

「來源」可指定為：

/data/sales

您可以將「to」指定為：

/backup/priorSales

在此案例中，來自 /data/sales 下的所有檔案皆會移至 /backup/priorSales。

注意

只有當您從使用管線中的執行資料流程活動所啟動的管線執行 (管線偵錯或執行) 開始資料流程時，檔案作業才會執行。 檔案操作不會在 Data Flow 偵錯模式下執行。

依上次修改時間篩選: 您可以指定檔案上次修改的日期範圍，以篩選您處理的檔案。 所有日期時間皆為國際標準時間。

查詢活動屬性

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

GetMetadata 活動屬性

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

刪除活動屬性

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

傳統模型

如果您使用 Amazon S3 連接器從 Google Cloud Storage 複製資料，則仍會按現狀提供支援，以提供回溯相容性。 建議您使用稍早所述的新模型。 撰寫 UI 已改為產生新模型。

相關內容

關於Copy activity支援的資料來源與匯項資料儲存清單，請參見 Supported data stores。

  • Last updated on