本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用資訊清單傳輸特定檔案或物件
*資訊清單*是您要 AWS DataSync 傳輸的檔案或物件清單。例如，DataSync 不需要傳輸 S3 儲存貯體中所有可能具有數百萬個物件的內容，而只會傳輸您在資訊清單中列出的物件。
資訊清單類似於[篩選條件](filtering.md)，但可讓您確切識別要傳輸哪些檔案或物件，而不是符合篩選條件模式的資料。
**注意**
具有增強型模式任務的資訊清單檔案允許的大小上限為 20 GB。
## 建立資訊清單
資訊清單是逗號分隔值 (CSV) 格式的檔案，列出您要 DataSync 傳輸之來源位置中的檔案或物件。如果您的來源是 S3 儲存貯體，您也可以包含要傳輸的物件版本。
**Topics**
+ [
### 指導方針
](#transferring-with-manifest-guidelines)
+ [
### 範例資訊清單
](#manifest-examples)
### 指導方針
使用這些準則來協助您建立可搭配 DataSync 使用的資訊清單。
------
#### [ Do ]
+ 指定您要傳輸之每個檔案或物件的完整路徑。
您無法僅指定意圖轉移其所有內容的目錄或資料夾。對於這些情況，請考慮使用[包含篩選條件](filtering.md)而非資訊清單。
+ 請確定每個檔案或物件路徑與您在設定 DataSync 來源位置時指定的掛載路徑、資料夾、目錄或字首相關。
例如，假設您使用名為 的字首[來設定 S3 位置](create-s3-location.md#create-s3-location-how-to)`photos`。該字首包含您要傳輸`my-picture.png`的物件。在資訊清單中，您接著只需要指定物件 (`my-picture.png`) 而非字首和物件 (`photos/my-picture.png`)。
+ 若要指定 Amazon S3 物件版本 IDs，請使用逗號分隔物件的路徑和版本 ID。
下列範例顯示包含兩個欄位的資訊清單項目。第一個欄位包含名為 的物件`picture1.png`。第二個欄位以逗號分隔，並包含 的版本 ID`111111`：
```
picture1.png,111111
```
+ 在下列情況下使用引號：
+ 當路徑包含特殊字元 （逗號、引號和行尾） 時：
`"filename,with,commas.txt"`
+ 當路徑跨越多行時：
```
"this
is
a
filename.txt"
```
+ 當路徑包含引號時：
`filename""with""quotes.txt`
這表示名為 的路徑`filename"with"quotes.txt`。
這些引號規則也適用於版本 ID 欄位。一般而言，如果資訊清單欄位有引號，您必須使用另一個引號逸出它。
+ 使用新行分隔每個檔案或物件項目。
您可以使用 Linux （換行或換行） 或 Windows （換行後接換行） 樣式換行來分隔行。
+ 儲存資訊清單 （例如， `my-manifest.csv`或 `my-manifest.txt`)。
+ 將資訊清單上傳至 [DataSync 可存取](#transferring-with-manifest-access)的 S3 儲存貯體。
此儲存貯體不必位於您使用 DataSync 的相同 AWS 區域 或 帳戶中。
------
#### [ Don't ]
+ 僅指定旨在傳輸其所有內容的目錄或資料夾。
資訊清單只能包含您要傳輸之檔案或物件的完整路徑。如果您將來源位置設定為使用特定掛載路徑、資料夾、目錄或字首，則不需要將其包含在資訊清單中。
+ 指定超過 4，096 個字元的檔案或物件路徑。
+ 指定超過 1，024 個位元組的檔案路徑、物件路徑或 Amazon S3 物件版本 ID。
+ 指定重複的檔案或物件路徑。
+ 如果您的來源位置不是 S3 儲存貯體，請包含物件版本 ID。
+ 在資訊清單項目中包含兩個以上的欄位。
項目只能包含檔案或物件路徑，以及 （如適用） Amazon S3 物件版本 ID。
+ 包含不符合 UTF-8 編碼的字元。
+ 在引號外的輸入欄位中包含意外空格。
------
### 範例資訊清單
使用這些範例來協助您建立可搭配 DataSync 使用的資訊清單。
**具有完整檔案或物件路徑的資訊清單**
下列範例顯示資訊清單，其中包含要傳輸的完整檔案或物件路徑。
```
photos/picture1.png
photos/picture2.png
photos/picture3.png
```
**僅具有物件索引鍵的資訊清單**
下列範例顯示資訊清單，其中包含要從 Amazon S3 來源位置傳輸的物件。由於[位置是以](create-s3-location.md#create-s3-location-how-to)字首 設定`photos`，因此只會指定物件金鑰。
```
picture1.png
picture2.png
picture3.png
```
**具有物件路徑和版本 IDs清單**
下列資訊清單範例中的前兩個項目包含要傳輸的特定 Amazon S3 物件版本。
```
photos/picture1.png,111111
photos/picture2.png,121212
photos/picture3.png
```
**帶有 UTF-8 字元的資訊清單**
下列範例顯示包含 UTF-8 字元的檔案資訊清單。
```
documents/résumé1.pdf
documents/résumé2.pdf
documents/résumé3.pdf
```
## 提供對資訊清單的 DataSync 存取權
您需要一個 AWS Identity and Access Management (IAM) 角色，讓 DataSync 存取 S3 儲存貯體中的資訊清單。此角色必須包含下列許可：
+ `s3:GetObject`
+ `s3:GetObjectVersion`
您可以在 DataSync 主控台中自動產生此角色，或自行建立角色。
**注意**
如果您的資訊清單位於不同的 AWS 帳戶中，您必須手動建立此角色。
### 自動建立 IAM 角色
在主控台中建立或啟動傳輸任務時，DataSync 可以使用存取資訊清單所需的 `s3:GetObject`和 `s3:GetObjectVersion`許可，為您建立 IAM 角色。
**自動建立角色所需的許可**
若要自動建立角色，請確定您用來存取 DataSync 主控台的角色具有下列許可：
+ `iam:CreateRole`
+ `iam:CreatePolicy`
+ `iam:AttachRolePolicy`
### 建立 IAM 角色 （相同帳戶）
您可以手動建立 DataSync 存取資訊清單所需的 IAM 角色。下列指示假設您使用 DataSync AWS 帳戶 的所在位置與資訊清單的 S3 儲存貯體所在的位置相同。
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在左側導覽窗格的**存取管理**下，選擇**角色**，然後選擇**建立角色**。
1. 在**選取信任的實體**頁面上，針對**信任的實體類型**，選擇 **AWS 服務**。
1. 針對**使用案例**，在下拉式清單中選擇 **DataSync**，然後選取 **DataSync**。選擇**下一步**。
1. 在 **Add permissions** (新增許可) 頁面上，選擇 **Next** (下一步)。為您的角色命名，然後選擇**建立角色**。
1. 在**角色**頁面上，搜尋您剛建立的角色，然後選擇其名稱。
1. 在角色的詳細資訊頁面上，選擇**許可**索引標籤。選擇**新增許可**，然後選擇**建立內嵌政策**。
1. 選擇 **JSON** 索引標籤，並將下列範例政策貼到政策編輯器中：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "DataSyncAccessManifest",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/my-manifest.csv"
}]
}
```
------
1. 在您剛貼上的範例政策中，將下列值取代為您自己的值：
1. `amzn-s3-demo-bucket` 將 取代為託管資訊清單的 S3 儲存貯體名稱。
1. `my-manifest.csv` 將 取代為您資訊清單的檔案名稱。
1. 選擇**下一步**。為您的政策命名，然後選擇**建立政策**。
1. （建議） 若要防止[跨服務混淆代理人問題](cross-service-confused-deputy-prevention.md)，請執行下列動作：
1. 在角色的詳細資訊頁面上，選擇**信任關係**索引標籤。選擇**編輯信任政策**。
1. 使用以下範例更新信任政策，其中包含 `aws:SourceArn`和 `aws:SourceAccount`全域條件內容索引鍵：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "datasync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "555555555555"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:datasync:us-east-1:555555555555:*"
}
}
}
]
}
```
------
+ `account-id` 使用 DataSync 所在的 AWS 帳戶 ID 取代每個執行個體。
+ `region` 將 取代為您使用 DataSync AWS 區域 的 。
1. 選擇**更新政策**。
您已建立允許 DataSync 存取資訊清單的 IAM 角色。在[建立](#manifest-creating-task)或[啟動](#manifest-starting-task)任務時指定此角色。
### 建立 IAM 角色 （不同的帳戶）
如果您的資訊清單位於屬於不同 的 S3 儲存貯體中 AWS 帳戶，您必須手動建立 DataSync 用來存取資訊清單的 IAM 角色。然後，在 AWS 帳戶 資訊清單所在的 中，您需要在 S3 儲存貯體政策中包含 角色。
#### 建立 角色
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在左側導覽窗格的**存取管理**下，選擇**角色**，然後選擇**建立角色**。
1. 在**選取信任的實體**頁面上，針對**信任的實體類型**，選擇 **AWS 服務**。
1. 針對**使用案例**，在下拉式清單中選擇 **DataSync**，然後選取 **DataSync**。選擇**下一步**。
1. 在 **Add permissions** (新增許可) 頁面上，選擇 **Next** (下一步)。為您的角色命名，然後選擇**建立角色**。
1. 在**角色**頁面上，搜尋您剛建立的角色，然後選擇其名稱。
1. 在角色的詳細資訊頁面上，選擇**許可**索引標籤。選擇**新增許可**，然後選擇**建立內嵌政策**。
1. 選擇 **JSON** 索引標籤，並將下列範例政策貼到政策編輯器中：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "DataSyncAccessManifest",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/my-manifest.csv"
}]
}
```
------
1. 在您剛貼上的範例政策中，將下列值取代為您自己的值：
1. `amzn-s3-demo-bucket` 將 取代為託管資訊清單的 S3 儲存貯體名稱。
1. `my-manifest.csv` 將 取代為您資訊清單的檔案名稱。
1. 選擇**下一步**。為您的政策命名，然後選擇**建立政策**。
1. （建議） 若要防止[跨服務混淆代理人問題](cross-service-confused-deputy-prevention.md)，請執行下列動作：
1. 在角色的詳細資訊頁面上，選擇**信任關係**索引標籤。選擇**編輯信任政策**。
1. 使用以下範例更新信任政策，其中包含 `aws:SourceArn`和 `aws:SourceAccount`全域條件內容索引鍵：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "datasync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "000000000000"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:datasync:us-east-1:000000000000:*"
}
}
}
]
}
```
------
+ `account-id` 使用 DataSync 所在的 AWS 帳戶 ID 取代 的每個執行個體。
+ `region` 將 取代為您使用 DataSync AWS 區域 的 。
1. 選擇**更新政策**。
您已建立可以包含在 S3 儲存貯體政策中的 IAM 角色。
#### 使用 角色更新您的 S3 儲存貯體政策
建立 IAM 角色之後，您必須將其新增至 AWS 帳戶 資訊清單所在的另一個 中的 S3 儲存貯體政策。
1. 在 中 AWS 管理主控台，使用您 Manfiest 的 S3 儲存貯體切換到帳戶。
1. 開啟位於 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
1. 在儲存貯體的詳細資訊頁面上，選擇**許可**索引標籤。
1. 在**儲存貯體政策**下，選擇**編輯**並執行下列動作來修改 S3 儲存貯體政策：
1. 更新編輯器中的內容，以包含下列政策陳述式：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DataSyncAccessManifestBucket",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket"
}
]
}
```
------
1. `account-id` 將 取代為您使用 DataSync 之帳戶的 AWS 帳戶 ID。
1. `datasync-role` 將 取代為您剛建立的 IAM 角色，以允許 DataSync 存取您的資訊清單。
1. `amzn-s3-demo-bucket` 將 取代為在另一個 中託管資訊清單的 S3 儲存貯體名稱 AWS 帳戶。
1. 選擇**儲存變更**。
您已建立 IAM 角色，允許 DataSync 存取您在其他帳戶中的資訊清單。在[建立](#manifest-creating-task)或[啟動](#manifest-starting-task)任務時指定此角色。
## 在建立任務時指定資訊清單
您可以指定您要 DataSync 在建立任務時使用的資訊清單。
### 使用 DataSync 主控台
1. 在 https：//[https://console.aws.amazon.com/datasync/](https://console.aws.amazon.com/datasync/) 開啟 AWS DataSync 主控台。
1. 在左側導覽窗格中，選擇**任務**，然後選擇**建立任務**。
1. 設定任務的來源和目的地位置。
如需詳細資訊，請參閱[我可以將資料傳輸到哪裡 AWS DataSync？](working-with-locations.md)
1. 針對**要掃描的內容**，選擇**特定檔案、物件和資料夾**，然後選取**使用資訊清單**。
1. 針對 **S3 URI**，選擇託管在 S3 儲存貯體上的資訊清單。
或者，您可以輸入 URI （例如，`s3://bucket/prefix/my-manifest.csv`)。
1. 針對**物件版本**，選擇您希望 DataSync 使用的資訊清單版本。
根據預設，DataSync 會使用物件的最新版本。
1. 對於**資訊清單存取角色**，請執行下列其中一項操作：
+ 選擇**自動產生** DataSync，以自動建立具有存取 S3 儲存貯體中資訊清單所需許可的 IAM 角色。
+ 選擇可存取資訊清單的現有 IAM 角色。
如需詳細資訊，請參閱[提供對資訊清單的 DataSync 存取權](#transferring-with-manifest-access)。
1. 設定您需要的任何其他任務設定，然後選擇**下一步**。
1. 選擇 **Create task (建立任務)**。
### 使用 AWS CLI
1. 複製下列`create-task`命令：
```
aws datasync create-task \
--source-location-arn arn:aws:datasync:us-east-1:123456789012:location/loc-12345678abcdefgh \
--destination-location-arn arn:aws:datasync:us-east-1:123456789012:location/loc-abcdefgh12345678 \
--manifest-config {
"Source": {
"S3": {
"ManifestObjectPath": "s3-object-key-of-manifest",
"BucketAccessRoleArn": "bucket-iam-role",
"S3BucketArn": "amzn-s3-demo-bucket-arn",
"ManifestObjectVersionId": "manifest-version-to-use"
}
}
}
```
1. 針對 `--source-location-arn` 參數，指定您要從中傳輸資料之位置的 Amazon Resource Name (ARN)。
1. 針對 `--destination-location-arn` 參數，指定您要傳輸資料之位置的 ARN。
1. 針對 `--manifest-config` 參數，請執行下列動作：
+ `ManifestObjectPath` – 指定資訊清單的 S3 物件金鑰。
+ `BucketAccessRoleArn` – 指定允許 DataSync 存取 S3 儲存貯體中資訊清單的 IAM 角色。
如需詳細資訊，請參閱[提供對資訊清單的 DataSync 存取權](#transferring-with-manifest-access)。
+ `S3BucketArn` – 指定託管資訊清單之 S3 儲存貯體的 ARN。
+ `ManifestObjectVersionId` – 指定您希望 DataSync 使用的資訊清單版本。
根據預設，DataSync 會使用物件的最新版本。
1. 執行 `create-task`命令來建立您的任務。
當您準備好時，可以[開始傳輸任務](run-task.md)。
## 在開始任務時指定資訊清單
您可以指定您希望 DataSync 在執行任務時使用的資訊清單。
### 使用 DataSync 主控台
1. 在 https：//[https://console.aws.amazon.com/datasync/](https://console.aws.amazon.com/datasync/) 開啟 AWS DataSync 主控台。
1. 在左側導覽窗格中，選擇**任務**，然後選擇您要開始的任務。
1. 在任務概觀頁面中，選擇**開始**，然後選擇**從覆寫選項開始**。
1. 針對**要掃描的內容**，選擇**特定檔案、物件和資料夾**，然後選取**使用資訊清單**。
1. 針對 **S3 URI**，選擇託管在 S3 儲存貯體上的資訊清單。
或者，您可以輸入 URI （例如，`s3://bucket/prefix/my-manifest.csv`)。
1. 針對**物件版本**，選擇您希望 DataSync 使用的資訊清單版本。
根據預設，DataSync 會使用物件的最新版本。
1. 對於**資訊清單存取角色**，請執行下列其中一項操作：
+ 選擇**自動產生** DataSync 以自動建立 IAM 角色，以存取 S3 儲存貯體中的資訊清單。
+ 選擇可存取資訊清單的現有 IAM 角色。
如需詳細資訊，請參閱[提供對資訊清單的 DataSync 存取權](#transferring-with-manifest-access)。
1. 選擇**開始**以開始轉移。
### 使用 AWS CLI
1. 複製下列`start-task-execution`命令：
```
aws datasync start-task-execution \
--task-arn arn:aws:datasync:us-east-1:123456789012:task/task-12345678abcdefgh \
--manifest-config {
"Source": {
"S3": {
"ManifestObjectPath": "s3-object-key-of-manifest",
"BucketAccessRoleArn": "bucket-iam-role",
"S3BucketArn": "amzn-s3-demo-bucket-arn",
"ManifestObjectVersionId": "manifest-version-to-use"
}
}
}
```
1. 針對 `--task-arn` 參數，指定您要啟動之任務的 Amazon Resource Name (ARN)。
1. 針對 `--manifest-config` 參數，請執行下列動作：
+ `ManifestObjectPath` – 指定資訊清單的 S3 物件金鑰。
+ `BucketAccessRoleArn` – 指定允許 DataSync 存取 S3 儲存貯體中資訊清單的 IAM 角色。
如需詳細資訊，請參閱[提供對資訊清單的 DataSync 存取權](#transferring-with-manifest-access)。
+ `S3BucketArn` – 指定託管資訊清單之 S3 儲存貯體的 ARN。
+ `ManifestObjectVersionId` – 指定您希望 DataSync 使用的資訊清單版本。
根據預設，DataSync 會使用物件的最新版本。
1. 執行 `start-task-execution`命令以開始傳輸。
## 限制
+ 您無法將資訊清單與[篩選條件](filtering.md)一起使用。
+ 您無法只指定旨在傳輸其所有內容的目錄或資料夾。對於這些情況，請考慮使用[包含篩選條件](filtering.md)而非資訊清單。
+ 您無法使用**保留已刪除的檔案**任務選項 (`PreserveDeletedFiles`在 [API](https://docs.aws.amazon.com/datasync/latest/userguide/API_Options.html#DataSync-Type-Options-PreserveDeletedFiles) 中） 來[維護目的地中不在來源中的檔案或物件](configure-metadata.md)。DataSync 只會傳輸資訊清單中列出的內容，而不會刪除目的地中的任何內容。
## 疑難排解
**與 `HeadObject`或 相關的錯誤 `GetObjectTagging`**
如果您要從 S3 儲存貯體傳輸具有特定版本 IDs物件，您可能會看到與 `HeadObject`或 相關的錯誤`GetObjectTagging`。例如，以下是與 相關的錯誤`GetObjectTagging`：
```
[WARN] Failed to read metadata for file /picture1.png (versionId: 111111): S3 Get Object Tagging Failed
[ERROR] S3 Exception: op=GetObjectTagging photos/picture1.png, code=403, type=15, exception=AccessDenied,
msg=Access Denied req-hdrs: content-type=application/xml, x-amz-api-version=2006-03-01 rsp-hdrs: content-type=application/xml,
date=Wed, 07 Feb 2024 20:16:14 GMT, server=AmazonS3, transfer-encoding=chunked,
x-amz-id-2=IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km, x-amz-request-id=79104EXAMPLEB723
```
如果您看到這些錯誤，請驗證 DataSync 用來存取 S3 來源位置的 IAM 角色具有下列許可：
+ `s3:GetObjectVersion`
+ `s3:GetObjectVersionTagging`
如果您需要使用這些許可更新角色，請參閱 [為 DataSync 建立 IAM 角色以存取您的 Amazon S3 位置](create-s3-location.md#create-role-manually)。
**錯誤：`ManifestFileDoesNotExist`**
此錯誤表示在來源找不到資訊清單內的檔案。檢閱建立資訊清單的[指導方針](#transferring-with-manifest-guidelines)。
## 後續步驟
如果您尚未開始任務，請[啟動您的任務](run-task.md)。否則，請[監控任務的活動](monitoring-overview.md)。