**請注意**：Amazon WorkDocs 不再提供新客戶註冊和帳戶升級。在此處了解遷移步驟：[如何從 WorkDocs 遷移資料](https://aws.amazon.com/blogs/business-productivity/how-to-migrate-content-from-amazon-workdocs)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用者應用程式的身分驗證與存取控制
<a name="wd-auth-user"></a>

WorkDocs 使用者層級應用程式是透過 WorkDocs 主控台註冊和管理。開發人員應該在 WorkDocs 主控台的 `My Applications` 頁面上註冊其應用程式，該主控台會為每個應用程式提供唯一的 IDs。在註冊期間，開發人員應指定重新導向 URI，以讓他們接收存取字符以及應用程式範圍。

目前，應用程式只能在註冊的相同 AWS 帳戶中存取 WorkDocs 網站。

**Topics**
+ [授予呼叫 WorkDocs APIs許可](#api-auth)
+ [在 API 呼叫中使用資料夾 IDs](#use-folder-ids)
+ [建立應用程式](#wd-app-create-app)
+ [應用程式範圍](#wd-app-scopes)
+ [授權](#wd-authorization)
+ [叫用 WorkDocs APIs](#wd-auth-invoke)

## 授予呼叫 WorkDocs APIs許可
<a name="api-auth"></a>

命令列界面使用者必須擁有 WorkDocs 和 的完整許可 Directory Service。如果沒有許可，任何 API 呼叫都會傳回 **UnauthorizedResourceAccessException** 訊息。下列政策會授予完整許可。

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
          "workdocs:*",
          "ds:*",
          "ec2:CreateVpc",
          "ec2:CreateSubnet",
          "ec2:CreateNetworkInterface",
          "ec2:CreateTags",
          "ec2:CreateSecurityGroup",
          "ec2:DescribeVpcs",
          "ec2:DescribeSubnets",
          "ec2:DescribeNetworkInterfaces",
          "ec2:DescribeAvailabilityZones",
          "ec2:AuthorizeSecurityGroupEgress",
          "ec2:AuthorizeSecurityGroupIngress",
          "ec2:DeleteSecurityGroup",
          "ec2:DeleteNetworkInterface",
          "ec2:RevokeSecurityGroupEgress",
          "ec2:RevokeSecurityGroupIngress"
          ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

如果您想要授予唯讀許可，請使用此政策。

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
          "workdocs:Describe*",
          "ds:DescribeDirectories",       
          "ec2:DescribeVpcs",
          "ec2:DescribeSubnets"
          ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

在政策中，第一個動作會授予所有 WorkDocs `Describe`操作的存取權。`DescribeDirectories ` 動作會取得 Directory Service 目錄的相關資訊。Amazon EC2 操作可讓 WorkDocs 取得 VPCs和子網路的清單。

## 在 API 呼叫中使用資料夾 IDs
<a name="use-folder-ids"></a>

每當 API 呼叫存取資料夾時，您必須使用資料夾 ID，而不是資料夾名稱。例如，如果您傳遞 `client.get_folder(FolderId='MyDocs')`，API 呼叫會傳回 **UnauthorizedResourceAccessException** 訊息和下列 404 訊息。

```
client.get_folder(FolderId='MyDocs')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Users\{{user-name}}\AppData\Local\Programs\Python\Python36-32\lib\site-packages\botocore\client.py", line 253, in _api_call
    return self._make_api_call(operation_name, kwargs)
  File "C:\Users\{{user-name}}\AppData\Local\Programs\Python\Python36-32\lib\site-packages\botocore\client.py", line 557, in _make_api_call
    raise error_class(parsed_response, operation_name)
botocore.errorfactory.UnauthorizedResourceAccessException: An error occurred (UnauthorizedResourceAccessException) when calling the GetFolder operation: 
Principal [arn:aws:iam::395162986870:user/Aman] is not allowed to execute [workdocs:GetFolder] on the resource.
```

若要避免這種情況，請在資料夾的 URL 中使用 ID。

`{{site.workdocs}}/index.html#/folder/abc123def456ghi789jkl789mno4be7024df198736472dd50ca970eb22796082e3d489577`.

傳遞該 ID 會傳回正確的結果。

```
client.get_folder(FolderId='abc123def456ghi789jkl789mno4be7024df198736472dd50ca970eb22796082e3d489577')
{'ResponseMetadata': {'RequestId': 'f8341d4e-4047-11e7-9e70-afa8d465756c', 'HTTPStatusCode': 200, 'HTTPHeaders': {'x-amzn-requestid': 'f234564e-1234-56e7-89e7-a10fa45t789c', 'cache-control': 'private, no-cache, no-store, max-age=0', 'content-type': 'application/json', 'content-length': '733', 'date': 'Wed, 24 May 2017 06:12:30 GMT'}, 'RetryAttempts': 0}, 'Metadata': {'Id': 'abc123def456ghi789jkl789mno4be7024df198736472dd50ca970eb22796082e3d489577', 'Name': 'sentences', 'CreatorId': 'S-1-5-21-2125721135-1643952666-3011040551-2105&d-906724f1ce', 'ParentFolderId': '0a811a922403ae8e1d3c180f4975f38f94372c3d6a2656c50851c7fb76677363', 'CreatedTimestamp': datetime.datetime(2017, 5, 23, 12, 59, 13, 8000, tzinfo=tzlocal()), 'ModifiedTimestamp': datetime.datetime(2017, 5, 23, 13, 13, 9, 565000, tzinfo=tzlocal()), 'ResourceState': 'ACTIVE', 'Signature': 'b7f54963d60ae1d6b9ded476f5d20511'}}
```

## 建立應用程式
<a name="wd-app-create-app"></a>

身為 WorkDocs 管理員，請使用下列步驟建立您的應用程式。

**建立應用程式**

1. 開啟 WorkDocs 主控台，網址為 https：//[https://console.aws.amazon.com/zocalo/](https://console.aws.amazon.com/zocalo/)。

1. 選擇 **My Applications (我的應用程式)**、**Create an Application (建立應用程式)**。

1. 輸入下列值：  
**Application Name** (應用程式名稱)  
應用程式名稱。  
**電子郵件**  
與應用程式建立關聯的電子郵件地址。  
**Application Description** (應用程式描述)  
應用程式的描述。  
**Redirect URIs** (重新導向 URI)  
您希望 WorkDocs 重新導向流量的位置。  
**Application Scopes (應用程式範圍)**  
您希望您的應用程式擁有的讀取或寫入範圍。如需詳細資訊，請參閱[應用程式範圍](#wd-app-scopes)。

1. 選擇**建立**。

## 應用程式範圍
<a name="wd-app-scopes"></a>

WorkDocs 支援下列應用程式範圍：
+ 內容讀取 (`workdocs.content.read`)，可讓您的應用程式存取下列 WorkDocs APIs：
  + Get\* (取得)
  + Describe\* (描述)
+ 內容寫入 (`workdocs.content.write`)，可讓您的應用程式存取下列 WorkDocs APIs：
  + 建立\*
  + 更新\*
  + 刪除\*
  + Initiate\* (啟動)
  + Abort\* (中止)
  + Add\* (新增)
  + Remove\* (移除)

## 授權
<a name="wd-authorization"></a>

應用程式註冊完成後，應用程式可以代表任何 WorkDocs 使用者請求授權。若要這樣做，應用程式應造訪 WorkDocs OAuth 端點 `https://auth.amazonworkdocs.com/oauth`，並提供下列查詢參數：
+ 【必要】 `app_id`— 註冊應用程式時產生的應用程式 ID。
+ 【必要】 `auth_type`— 請求的 OAuth 類型。支援的值為 `ImplicitGrant`。
+ 【必要】 `redirect_uri`— 為應用程式註冊以接收存取字符的重新導向 URI。
+ 【選用】 `scopes`— 以逗號分隔的範圍清單。若未指定，將會使用該註冊期間選擇的範圍清單。
+ 【選用】 `state`— 與存取字符一起傳回的字串。

**注意**  
如果您在透過命令列介面或 API 存取 AWS 時，需要 FIPS 140-2 驗證的加密模組，請使用 FIPS 端點。如需有關 FIPS 和 FIPS 端點的更多相關資訊，請參閱[聯邦資訊處理標準 (FIPS) 140-2 概觀](https://aws.amazon.com/compliance/fips/)。

範例 GET 請求以啟動 OAuth 流程以取得存取字符：

```
GET https://auth.amazonworkdocs.com/oauth?app_id=my-app-id&auth_type=ImplicitGrant&redirect_uri=https://myapp.com/callback&scopes=workdocs.content.read&state=xyz
```

下列項目會在 OAuth 授權流程期間發生：

1. 系統會提示應用程式使用者輸入 WorkDocs 網站名稱。

1. 使用者會重新導向至 WorkDocs 身分驗證頁面，以輸入其登入資料。

1. 身分驗證成功後，使用者會收到同意畫面，允許使用者授予或拒絕應用程式存取 WorkDocs 的授權。

1. 在使用者選擇同意畫面上的 `Accept` 後，他們的瀏覽器將重新導向至您應用程式的回呼 URL，以及做為查詢參數的存取字符與區域資訊。

WorkDocs 的範例 GET 請求：

```
GET https://myapp.com/callback?acessToken=accesstoken&region=us-east-1&state=xyz
```

除了存取權杖之外，WorkDocs OAuth 服務也會傳回`region`為所選 WorkDocs 網站的查詢參數。外部應用程式應使用 `region` 參數來判斷 WorkDocs 服務端點。

如果您在透過命令列介面或 API 存取 AWS 時，需要 FIPS 140-2 驗證的加密模組，請使用 FIPS 端點。如需有關 FIPS 和 FIPS 端點的更多相關資訊，請參閱[聯邦資訊處理標準 (FIPS) 140-2 概觀](https://aws.amazon.com/compliance/fips/)。

## 叫用 WorkDocs APIs
<a name="wd-auth-invoke"></a>

取得存取權杖後，您的應用程式可以對 WorkDocs 服務進行 API 呼叫。

**重要**  


此範例說明如何使用 curl GET 請求來取得文件的中繼資料。

```
Curl "https://workdocs.us-east-1.amazonaws.com/api/v1/documents/{document-id}" -H "Accept: application/json" -H "Authentication: Bearer accesstoken"
```

描述使用者根資料夾的範例 JavaScript 函數：

```
function printRootFolders(accessToken, siteRegion) {
    var workdocs = new AWS.WorkDocs({region: siteRegion});
    workdocs.makeUnauthenticatedRequest("describeRootFolders", {AuthenticationToken: accessToken}, function (err, folders) {
        if (err) console.log(err);
        else console.log(folders);
    });     
}
```

以 Java 為基礎的 API 呼叫範例描述如下：

```
AWSCredentialsProvider credentialsProvider = new AWSCredentialsProvider() {
  @Override
  public void refresh() {}

  @Override
  public AWSCredentials getCredentials() {
    new AnonymousAWSCredentials();
  }
};

// Set the correct region obtained during OAuth flow.
workDocs =
    AmazonWorkDocsClient.builder().withCredentials(credentialsProvider)
        .withRegion(Regions.US_EAST_1).build();

DescribeRootFoldersRequest request = new DescribeRootFoldersRequest();
request.setAuthenticationToken("access-token-obtained-through-workdocs-oauth");
DescribeRootFoldersResult result = workDocs.describeRootFolders(request);

for (FolderMetadata folder : result.getFolders()) {
  System.out.printf("Folder name=%s, Id=%s \n", folder.getName(), folder.getId());
}
```