授予调用 Amazon WorkDocs API 的权限在 API 调用中使用文件夹 ID 创建应用程序应用程序范围授权调用 Amazon WorkDocs API

用户应用程序的身份验证和访问控制

Amazon WorkDocs 用户级应用程序是通过 Amazon WorkDocs 控制台注册和管理的。开发人员应在 Amazon WorkDocs 控制台上的 My Applications 页面上注册其应用程序，该页面将为每个应用程序提供唯一的 ID。在注册过程中，开发人员应指定要接收访问令牌的重定向 URI 以及应用程序范围。

当前，应用程序只能访问在其注册的同一 AWS 账户中的 Amazon WorkDocs 站点。

授予调用 Amazon WorkDocs API 的权限

命令行界面用户必须拥有对 Amazon WorkDocs 和 AWS 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": "*"
    }
  ]
}

在该策略中，第一个操作授予对所有 Amazon WorkDocs Describe 操作的访问权限。DescribeDirectories 操作获取有关 AWS Directory Service 目录的信息。Amazon EC2 操作使 Amazon WorkDocs 能够获取您的 VPC 和子网的列表。

在 API 调用中使用文件夹 ID

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

创建应用程序

作为 Amazon WorkDocs 管理员，请使用以下步骤创建应用程序。

创建应用程序

打开 Amazon WorkDocs 控制台，网址为：https://console.aws.amazon.com/zocalo/。
依次选择我的应用程序和创建应用程序。
输入以下值：

应用程序名称

应用程序的名称。

电子邮件

要与应用程序关联的电子邮件地址。

应用程序描述

应用程序的描述。

重定向 URI

希望 Amazon WorkDocs 将流量重定向到的位置。

应用程序范围

希望应用程序具有的读取或写入范围。有关更多详细信息，请参阅应用程序范围。
选择创建。

应用程序范围

Amazon WorkDocs 支持以下应用程序范围：

内容读取 (workdocs.content.read)，它使您的应用程序可以访问以下 Amazon WorkDocs API：
- Get*
- Describe*
内容写入 (workdocs.content.write)，它使您的应用程序可以访问以下 Amazon WorkDocs API：
- Create*
- Update*
- Delete*
- Initiate*
- Abort*
- Add*
- Remove*

授权

应用程序注册完成后，应用程序可以代表任何 Amazon WorkDocs 用户请求授权。为此，应用程序应访问 Amazon 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) 第 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 授权流程中：

系统会提示应用程序用户输入 Amazon WorkDocs 站点名称。
用户将被重定向到 Amazon WorkDocs 身份验证页面以输入其凭证。
成功进行身份验证后，系统会向用户显示同意屏幕，允许用户向您的应用程序授予或拒绝访问 Amazon WorkDocs 的授权。
在用户选择同意屏幕上的 Accept 后，他们的浏览器将连同作为查询参数的访问令牌和区域信息一起被重定向到应用程序的回调 URL。

来自 Amazon WorkDocs 的 GET 请求示例：


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

除访问令牌外，Amazon WorkDocs OAuth 服务还会将 region 作为选定 Amazon WorkDocs 站点的查询参数返回。外部应用程序应使用 region 参数确定 Amazon WorkDocs 服务端点。

调用 Amazon WorkDocs API

在获取访问令牌后，应用程序可以对 Amazon 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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

限制对特定 Amazon WorkDocs 实例的访问权限

Amazon WorkDocs 内容管理器