授予呼叫 WorkDocs APIs許可在 API 呼叫中使用資料夾 IDs 建立應用程式應用程式範圍授權叫用 WorkDocs APIs

使用者應用程式的身分驗證與存取控制

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

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

授予呼叫 WorkDocs APIs許可

命令列界面使用者必須擁有 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

每當 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'}}

建立應用程式

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

建立應用程式

開啟 WorkDocs 主控台，網址為 https：//https://console.aws.amazon.com/zocalo/。
選擇 My Applications (我的應用程式)、Create an Application (建立應用程式)。
輸入下列值：

Application Name (應用程式名稱)

應用程式名稱。

電子郵件

與應用程式建立關聯的電子郵件地址。

Application Description (應用程式描述)

應用程式的描述。

Redirect URIs (重新導向 URI)

您希望 WorkDocs 重新導向流量的位置。

Application Scopes (應用程式範圍)

您希望您的應用程式擁有的讀取或寫入範圍。如需詳細資訊，請參閱應用程式範圍。
選擇建立。

應用程式範圍

WorkDocs 支援下列應用程式範圍：

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

授權

應用程式註冊完成後，應用程式可以代表任何 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 概觀。

範例 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 授權流程期間發生：

系統會提示應用程式使用者輸入 WorkDocs 網站名稱。
使用者會重新導向至 WorkDocs 身分驗證頁面，以輸入其登入資料。
身分驗證成功後，使用者會收到同意畫面，允許使用者授予或拒絕應用程式存取 WorkDocs 的授權。
在使用者選擇同意畫面上的 Accept 後，他們的瀏覽器將重新導向至您應用程式的回呼 URL，以及做為查詢參數的存取字符與區域資訊。

WorkDocs 的範例 GET 請求：


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

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

叫用 WorkDocs APIs

取得存取權杖後，您的應用程式可以對 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());
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

限制對特定 WorkDocs 執行個體的存取

WorkDocs 內容管理員