Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS...

23
Amazon WorkDocs 開発者ガイド

Transcript of Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS...

Page 1: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs開発者ガイド

Page 2: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイド

Amazon WorkDocs: 開発者ガイドCopyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's,in any manner that is likely to cause confusion among customers, or in any manner that disparages or discreditsAmazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may notbe affiliated with, connected to, or sponsored by Amazon.

Page 3: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイド

Table of ContentsAmazon WorkDocs とは ...................................................................................................................... 1

アクセス .................................................................................................................................... 1料金表 ....................................................................................................................................... 1リソース .................................................................................................................................... 1

開始方法 ............................................................................................................................................ 3IAM ユーザー認証情報を使用して Amazon WorkDocs に接続する ...................................................... 3ロールを割り当てて Amazon WorkDocs に接続する ........................................................................ 4ドキュメントをアップロードする .................................................................................................. 6ドキュメントをダウンロードする .................................................................................................. 7通知へのサブスクライブ .............................................................................................................. 7新しいユーザーの作成 ................................................................................................................. 8リソースでユーザーにアクセス許可を追加する ............................................................................... 9

管理アプリケーションの認証とアクセスコントロール ............................................................................ 10開発者に Amazon WorkDocs API へのアクセス許可を付与する ........................................................ 10サードパーティー開発者にアクセス許可を付与する ........................................................................ 11IAM ロールを割り当てるためのアクセス許可を開発者に付与する ..................................................... 12特定の Amazon WorkDocs インスタンスへのアクセスの制限 .......................................................... 12IAM ユーザーまたはロールの通知の管理 ...................................................................................... 13

ユーザーアプリケーションの認証とアクセスコントロール ...................................................................... 14アプリケーションの作成 ............................................................................................................ 14アプリケーションスコープ ......................................................................................................... 15承認 ........................................................................................................................................ 15Amazon WorkDocs API の呼び出し ............................................................................................. 16

Amazon WorkDocs コンテンツマネージャ ............................................................................................ 17Amazon WorkDocs コンテンツマネージャの構築 ........................................................................... 17ドキュメントのダウンロード ...................................................................................................... 18ドキュメントのアップロード ...................................................................................................... 18

AWS の用語集 .................................................................................................................................. 20

iii

Page 4: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドアクセス

Amazon WorkDocs とはAmazon WorkDocs は、完全マネージド型のセキュアなエンタープライズストレージおよび共有サービスであり、強固な管理コントロールと、ユーザーの生産性を向上するためのフィードバック機能を備えています。ファイルは、クラウド内に安全に保存されます。ユーザーのファイルは、ユーザーのみ、またはユーザーが指定したコントリビュータとビューワーのみが閲覧できます。ユーザーの組織のその他の方は、ユーザーが特別なアクセス許可を付与しない限り、ユーザーのいずれのファイルへもアクセスすることができません。

ユーザーはコラボレーション、または、レビューの目的で、その他の方とファイルを共用することができます。Amazon WorkDocs のクライアントアプリケーションは、ファイルのインターネットメディアタイプに応じて、さまざまな種類のファイルの表示に使用されます。Amazon WorkDocs では、一般的なドキュメント形式やイメージ形式がサポートされているほか、メディアタイプのサポートは定期的に追加されています。

詳細については、「Amazon WorkDocs」を参照してください。

アクセスエンドユーザーはクライアントアプリケーションを使用してファイルにアクセスします。管理者以外のユーザーは、Amazon WorkDocs コンソールまたは管理ダッシュボードを使用する必要はありません。Amazon WorkDocs には、いくつかの異なるクライアントアプリケーションとユーティリティが用意されています。

• ドキュメント管理とレビューに使用するウェブアプリケーション。• ドキュメントレビューに使用するモバイルデバイス用ネイティブアプリケーション。• Mac または Windows デスクトップ上のフォルダを Amazon WorkDocs ファイルと同期するために使用

するドキュメント同期アプリケーション。• ウェブページの画像を Amazon WorkDocs ファイルに保存できるウェブクリッパーのブラウザ拡張機

能。いくつかの人気の高いウェブブラウザ向けが用意されています。

料金表Amazon WorkDocs に前払い料金などの義務はありません。アクティブなユーザーアカウントと、使用するストレージに対する料金のみです。 詳細は、「料金表」を参照してください。

リソースこのサービスを利用する際に役立つ関連リソースは以下の通りです。

• クラスとワークショップ – AWS に関するスキルを磨き、実践的経験を積むために役立つ、職務別の特別コースとセルフペースラボへのリンクです。

• AWS 開発者用ツール – AWS アプリケーションの開発と管理のための開発者ツール、SDK、IDE ツールキット、およびコマンドラインツールへのリンクです。

• AWS ホワイトペーパー – アーキテクチャー、セキュリティ、エコノミクスなどのトピックをカバーし、AWS のソリューションアーキテクトや他の技術エキスパートによって書かれた、技術的な AWS ホワイトペーパーの包括的なリストへのリンクです。

1

Page 5: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドリソース

• AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技術上のよくある質問、サービス状態ステータス、AWS Trusted Advisor などの便利なリソースへのリンクも含まれています。

• AWS サポート – 1 対 1 での迅速な対応を行うサポートチャネルである AWS サポートに関する情報のメインウェブページです。AWS サポートは、クラウドでのアプリケーションの構築および実行を支援します。

• お問い合わせ – AWS 請求、アカウント、イベント、不正使用、およびその他の問題に関する問い合わせ先です。

• AWS サイトの利用規約 – 当社の著作権、商標、お客様のアカウント、ライセンス、サイトへのアクセス、およびその他のトピックに関する詳細情報です。

2

Page 6: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドIAM ユーザー認証情報を使用し

て Amazon WorkDocs に接続する

開始方法以下のコードスニペットは、Amazon WorkDocs SDK の使用を開始するのに役立ちます。

例• IAM ユーザー認証情報とユーザーのクエリを使用して Amazon WorkDocs に接続する (p. 3)• ロールを割り当てて Amazon WorkDocs に接続し、ユーザーのルートフォルダを参照する (p. 4)• ドキュメントをアップロードする (p. 6)• ドキュメントをダウンロードする (p. 7)• 通知へのサブスクライブ (p. 7)• 新しいユーザーの作成 (p. 8)• リソースでユーザーにアクセス許可を追加する (p. 9)

IAM ユーザー認証情報とユーザーのクエリを使用して Amazon WorkDocs に接続する

次のコードは、AWS SDK を使用して、IAM ユーザーの API 認証情報を使用した API コールを行うステップを示します。この場合、API ユーザーと Amazon WorkDocs サイトは、同じ AWS アカウントに属しています。

IAM ユーザーに適切な IAM ポリシーを通して Amazon WorkDocs API アクセスが付与されていることを確認します。

コード例は、ユーザーを検索し、ユーザーにメタデータを取得するため、describeUsers API を使用します。ユーザーメタデータは、名、姓、ユーザー ID およびルートフォルダ ID などの詳細を提供します。ルートフォルダ ID は、ユーザーに代わってコンテンツのアップロードまたはダウンロード操作を行う場合に特に役立ちます。

コードには、Amazon WorkDocs 組織 ID の取得が必要です。

次の手順を使用して、AWS コンソールから Amazon WorkDocs 組織 ID を取得できます。

組織 ID を取得するには

1. AWS Directory Service console ナビゲーションペインで [Directories (ディレクトリ)] を選択します。2. Amazon WorkDocs サイトに対応するディレクトリ ID は、そのサイトの組織 ID です。

以下はコード例です。

import java.util.ArrayList;import java.util.List;

import com.amazonaws.auth.AWSCredentials;import com.amazonaws.auth.AWSStaticCredentialsProvider;import com.amazonaws.auth.BasicAWSCredentials;import com.amazonaws.regions.Regions;import com.amazonaws.services.workdocs.AmazonWorkDocs;import com.amazonaws.services.workdocs.AmazonWorkDocsClient;import com.amazonaws.services.workdocs.model.DescribeUsersRequest;

3

Page 7: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドロールを割り当てて Amazon WorkDocs に接続する

import com.amazonaws.services.workdocs.model.DescribeUsersResult;import com.amazonaws.services.workdocs.model.User;

public class GetUserDemo {

public static void main(String[] args) throws Exception { AWSCredentials longTermCredentials = new BasicAWSCredentials("accessKey", "secretKey"); AWSStaticCredentialsProvider staticCredentialProvider = new AWSStaticCredentialsProvider(longTermCredentials);

AmazonWorkDocs workDocs = AmazonWorkDocsClient.builder().withCredentials(staticCredentialProvider) .withRegion(Regions.US_WEST_2).build();

List<User> wdUsers = new ArrayList<>(); DescribeUsersRequest request = new DescribeUsersRequest(); // The OrganizationId used here is an example and it should be replaced // with the OrganizationId of your WorkDocs site. request.setOrganizationId("d-123456789c"); request.setQuery("joe"); String marker = null; do { request.setMarker(marker); DescribeUsersResult result = workDocs.describeUsers(request); wdUsers.addAll(result.getUsers()); marker = result.getMarker(); } while (marker != null); System.out.println("List of users matching the query string: joe "); for (User wdUser : wdUsers) { System.out.printf("Firstname:%s | Lastname:%s | Email:%s | root-folder-id:%s\n", wdUser.getGivenName(), wdUser.getSurname(), wdUser.getEmailAddress(), wdUser.getRootFolderId()); } }}

ロールを割り当てて Amazon WorkDocs に接続し、ユーザーのルートフォルダを参照する

このサンプルコードは、AWS Java SDK を使用して、ロールを引き受けるステップ、また AmazonWorkDocs にアクセスするためロールの一時的セキュリティ認証情報を使用する個々のステップを示します。このサンプルコードでは、describeFolderContents API を使用して、ユーザーのフォルダに存在する項目のリストを作成します。

import java.util.ArrayList;import java.util.List;

import com.amazonaws.auth.AWSCredentials;import com.amazonaws.auth.AWSStaticCredentialsProvider;import com.amazonaws.auth.BasicAWSCredentials;import com.amazonaws.auth.BasicSessionCredentials;import com.amazonaws.regions.Regions;import com.amazonaws.services.securitytoken.AWSSecurityTokenService;import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;import com.amazonaws.services.securitytoken.model.AssumeRoleRequest;

4

Page 8: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドロールを割り当てて Amazon WorkDocs に接続する

import com.amazonaws.services.securitytoken.model.AssumeRoleResult;import com.amazonaws.services.workdocs.AmazonWorkDocs;import com.amazonaws.services.workdocs.AmazonWorkDocsClient;import com.amazonaws.services.workdocs.model.DescribeFolderContentsRequest;import com.amazonaws.services.workdocs.model.DescribeFolderContentsResult;import com.amazonaws.services.workdocs.model.DocumentMetadata;import com.amazonaws.services.workdocs.model.FolderMetadata;

public class AssumeRoleDemo { private static final String DEMO_ROLE_ARN = "arn:aws:iam::111122223333:role/workdocs-readonly-role"; private static AmazonWorkDocs workDocs;

public static void main(String[] args) throws Exception {

AWSCredentials longTermCredentials = new BasicAWSCredentials("accessKey", "secretKey");

// Use developer’s long-term credentials to call the AWS Security Token Service (STS) // AssumeRole API, specifying the ARN for the role workdocs-readonly-role in // 3rd party AWS account.

AWSSecurityTokenService stsClient = AWSSecurityTokenServiceClientBuilder.standard() .withCredentials(new AWSStaticCredentialsProvider(longTermCredentials)) .withRegion(Regions.DEFAULT_REGION.getName()).build();;

// If you are accessing a 3rd party account, then ExternalId should // be set on assumeRequest using the withExternalId() function. AssumeRoleRequest assumeRequest = new AssumeRoleRequest().withRoleArn(DEMO_ROLE_ARN).withDurationSeconds(3600) .withRoleSessionName("demo");

AssumeRoleResult assumeResult = stsClient.assumeRole(assumeRequest);

// AssumeRole returns temporary temporary security credentials obtained // for workdocs-readonly-role

BasicSessionCredentials temporaryCredentials = new BasicSessionCredentials(assumeResult.getCredentials().getAccessKeyId(), assumeResult .getCredentials().getSecretAccessKey(), assumeResult.getCredentials().getSessionToken());

// Build WorkDocs client using the temporary credentials. workDocs = AmazonWorkDocsClient.builder() .withCredentials(new AWSStaticCredentialsProvider(temporaryCredentials)) .withRegion(Regions.US_WEST_2).build();

// Invoke WorkDocs service calls using the temporary security credentials // obtained for workdocs-readonly-role. In this case a call has been made // to get metadata of Folders and Documents present in a user’s root folder.

describeFolder("root-folder-id"); }

private static void describeFolder(String folderId) { DescribeFolderContentsRequest request = new DescribeFolderContentsRequest(); request.setFolderId(folderId); request.setLimit(2); List<DocumentMetadata> documents = new ArrayList<>(); List<FolderMetadata> folders = new ArrayList<>(); String marker = null;

5

Page 9: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドドキュメントをアップロードする

do { request.setMarker(marker); DescribeFolderContentsResult result = workDocs.describeFolderContents(request); documents.addAll(result.getDocuments()); folders.addAll(result.getFolders()); marker = result.getMarker(); } while (marker != null); for (FolderMetadata folder : folders) System.out.println("Folder:" + folder.getName()); for (DocumentMetadata document : documents) System.out.println("Document:" + document.getLatestVersionMetadata().getName()); }}

ドキュメントをアップロードする以下の手順を使用して、Amazon WorkDocs にドキュメントをアップロードします。

ドキュメントをアップロードするには

1. 次のように AmazonWorkDocsClient のインスタンスを作成します。

IAM ユーザー認証情報を使用している場合、「IAM ユーザー認証情報とユーザーのクエリを使用してAmazon WorkDocs に接続する (p. 3)」を参照してください。IAM ロールを割り当てている場合、詳細については「ロールを割り当てて Amazon WorkDocs に接続し、ユーザーのルートフォルダを参照する (p. 4)」を参照してください。

AWSCredentials longTermCredentials = new BasicAWSCredentials("accessKey", "secretKey");AWSStaticCredentialsProvider staticCredentialProvider = new AWSStaticCredentialsProvider(longTermCredentials);

// Use the region specific to your WorkDocs site.AmazonWorkDocs amazonWorkDocsClient = AmazonWorkDocsClient.builder().withCredentials(staticCredentialProvider) .withRegion(Regions.US_WEST_2).build();

2. アップロードのため、以下のように署名付き URL を取得します。

InitiateDocumentVersionUploadRequest request = new InitiateDocumentVersionUploadRequest();request.setParentFolderId("parent-folder-id");request.setName("my-document-name");request.setContentType("application/octet-stream");InitiateDocumentVersionUploadResult result = amazonWorkDocsClient.initiateDocumentVersionUpload(request);UploadMetadata uploadMetadata = result.getUploadMetadata();String documentId = result.getMetadata().getId();String documentVersionId = result.getMetadata().getLatestVersionMetadata().getId();String uploadUrl = uploadMetadata.getUploadUrl();

3. 署名付き URL を使用して、以下のようにドキュメントをアップロードします。

URL url = new URL(uploadUrl);HttpURLConnection connection = (HttpURLConnection) url.openConnection();connection.setDoOutput(true);connection.setRequestMethod("PUT");// Content-Type supplied here should match with the Content-Type set

6

Page 10: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドドキュメントをダウンロードする

// in the InitiateDocumentVersionUpload request.connection.setRequestProperty("Content-Type","application/octet-stream");connection.setRequestProperty("x-amz-server-side-encryption", "AES256");File file = new File("/path/to/file.txt");FileInputStream fileInputStream = new FileInputStream(file);OutputStream outputStream = connection.getOutputStream();com.amazonaws.util.IOUtils.copy(fileInputStream, outputStream);connection.getResponseCode();

4. 以下のようにドキュメントステータスを ACTIVE に変更して、アップロードプロセスを完了します。

UpdateDocumentVersionRequest request = new UpdateDocumentVersionRequest();request.setDocumentId("document-id");request.setVersionId("document-version-id");request.setVersionStatus(DocumentVersionStatus.ACTIVE);amazonWorkDocsClient.updateDocumentVersion(request);

ドキュメントをダウンロードするAmazon WorkDocs からドキュメントをダウンロードするには、以下のようにダウンロード用の URL を取得します。その後、URL を使って、開発プラットフォームが提供する API アクションを使用してファイルをダウンロードします。

GetDocumentVersionRequest request = new GetDocumentVersionRequest();request.setDocumentId("document-id");request.setVersionId("document-version-id");request.setFields("SOURCE");GetDocumentVersionResult result = amazonWorkDocsClient.getDocumentVersion(request);String downloadUrl = result.getMetadata().getSource().get(DocumentSourceType.ORIGINAL.name());

通知へのサブスクライブ特定のアクションが発生したときに Amazon WorkDocs が送信する通知をサブスクライブできます。

WorkDocs の通知をサブスクライブするには

1. Amazon SNS メッセージを処理するため、エンドポイントを準備します。詳細については、『Amazon Simple Notification Service 開発者ガイド』の「エンドポイントで Amazon SNS メッセージを処理する準備が完了していることを確認する」を参照してください。

2. アプリケーションが使用している IAM ロールの通知を有効にします。「IAM ユーザーまたはロールの通知の管理 (p. 13)」を参照してください。

3. サブスクリプションリクエストを次のように作成します。

CreateNotificationSubscriptionRequest request = new CreateNotificationSubscriptionRequest();request.setOrganizationId("d-1234567890");request.setProtocol(SubscriptionProtocolType.Https);request.setEndpoint("https://my-webhook-service.com/webhook");request.setSubscriptionType(SubscriptionType.ALL);CreateNotificationSubscriptionResult result = amazonWorkDocsClient.createNotificationSubscription(request);System.out.println("WorkDocs notifications subscription-id: " result.getSubscription().getSubscriptionId());

7

Page 11: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイド新しいユーザーの作成

[SNS Notifications]

メッセージには、次に示す情報が含まれます。

• organizationId — 組織の ID。• parentEntityType — 親のタイプ (Document | DocumentVersion | Folder)。• parentEntityId — 親の ID。• entityType — エンティティのタイプ (Document | DocumentVersion | Folder)。• entityId — エンティティの ID。• アクション — アクション。次のいずれかの値になります。

• delete_document

• move_document

• recycle_document

• rename_document

• revoke_share_document

• share_document

• upload_document_version

次の手順を使用して、AWS コンソールから Amazon WorkDocs 組織 ID を取得できます。

組織 ID を取得するには

1. AWS Directory Service console ナビゲーションペインで [Directories (ディレクトリ)] を選択します。2. Amazon WorkDocs サイトに対応するディレクトリ ID は、そのサイトの組織 ID です。

新しいユーザーの作成次のコードスニペットは、Amazon WorkDocs で新しいユーザーを作成するためのリクエストの構造を示します。

Note

これは、Connected AD 設定の有効なオペレーションではありません。Connected AD 設定で新しいユーザーを追加するには、企業ディレクトリにそのユーザーがすでに存在している必要があります。次に、ActivateUser API を呼び出して、Amazon WorkDocs のユーザーをアクティブ化する必要があります。

次の例では、1 ギガバイトのストレージクォータを使用して新しいユーザーを作成します。

CreateUserRequest request = new CreateUserRequest(); request.setGivenName("GivenName"); request.setOrganizationId("d-12345678c4"); // Passwords should: // Be between 8 and 64 characters // Contain three of the four below: // A Lowercase Character // An Uppercase Character // A Number // A Special Character request.setPassword("Badpa$$w0rd"); request.setSurname("surname"); request.setUsername("UserName"); StorageRuleType storageRule = new StorageRuleType(); storageRule.setStorageType(StorageType.QUOTA);

8

Page 12: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドリソースでユーザーにアクセス許可を追加する

storageRule.setStorageAllocatedInBytes(new Long(1048576l)); request.setStorageRule(storageRule); CreateUserResult result = workDocsClient.createUser(request);

次の手順を使用して、AWS コンソールから Amazon WorkDocs 組織 ID を取得できます。

組織 ID を取得するには

1. AWS Directory Service console ナビゲーションペインで [Directories (ディレクトリ)] を選択します。2. Amazon WorkDocs サイトに対応するディレクトリ ID は、そのサイトの組織 ID です。

リソースでユーザーにアクセス許可を追加する次のコードスニペットは、リソースでユーザーにアクセス許可を追加するためのリクエストの構造を説明します。この例では、リソースで USER に CONTRIBUTOR アクセス許可を追加しています。この API は、フォルダやドキュメントのユーザー、またはグループにアクセス許可を付与するためにも使用できます。

AddResourcePermissionsRequest request = new AddResourcePermissionsRequest(); request.setResourceId("resource-id"); Collection<SharePrincipal> principals = new ArrayList<>();; SharePrincipal principal = new SharePrincipal(); principal.setId("user-id"); principal.setType(PrincipalType.USER); principal.setRole(RoleType.CONTRIBUTOR); principals.add(principal); request.setPrincipals(principals); AddResourcePermissionsResult result = workDocsClient.addResourcePermissions(request);

9

Page 13: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイド開発者に Amazon WorkDocs API

へのアクセス許可を付与する

管理アプリケーションの認証とアクセスコントロール

Amazon WorkDocs 管理 API は、IAM ポリシーを使用して認証、認可されます。IAM 管理者は、IAM ポリシーを作成して、IAM ロールまたはユーザーにアタッチします。これらは、API にアクセスするために開発者によって使用されます。

例として以下のものが用意されています。

タスク• AWS アカウントで開発者に Amazon WorkDocs API へのアクセス許可を付与する (p. 10)• AWS アカウントでサードパーティー開発者に Amazon WorkDocs API へのアクセス許可を付与す

る (p. 11)• Amazon WorkDocs 顧客により与えられた IAM ロールを割り当てるためのアクセス許可を開発者に付

与する (p. 12)• 特定の Amazon WorkDocs インスタンスへのアクセスの制限 (p. 12)• IAM ユーザーまたはロールの通知の管理 (p. 13)

AWS アカウントで開発者に Amazon WorkDocsAPI へのアクセス許可を付与する

IAM 管理者は、同じ AWS アカウントの IAM ユーザーに Amazon WorkDocs API アクセスを許可することができます。そのためには、Amazon WorkDocs API アクセス許可ポリシーを作成して、IAM ユーザーにアタッチします。以下は、読み取り専用の API (API をリストし記述する) へのアクセス許可を付与するサンプル Amazon WorkDocs API ポリシーです。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "WorkDocsAPIReadOnly", "Effect": "Allow", "Action": [ "workdocs:Get*", "workdocs:Describe*" ], "Resource": [ "*" ] } ]}

10

Page 14: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドサードパーティー開発者にアクセス許可を付与する

AWS アカウントでサードパーティー開発者にAmazon WorkDocs API へのアクセス許可を付与する

アクセス権は、サードパーティーの開発者、または別の AWS アカウントを使用しているユーザーに付与することができます。そのためには、IAM ロールを作成し、Amazon WorkDocs API 許可ポリシーをアタッチします。

このアクセスのフォームは、以下のシナリオで必要です。

• 開発者は同じ組織に属していますが、開発者の AWS アカウントが Amazon WorkDocs AWS アカウントと異なる。

• 企業がサードパーティーアプリケーション開発者に Amazon WorkDocs API アクセスを付与する場合。

どちらのシナリオでも、開発者の AWS アカウントと、Amazon WorkDocs サイトをホスティングするアカウントの 2 つの AWS アカウントが必要です。

開発者は、アカウント管理者が IAM ロールを作成できるように、次の情報を提供する必要があります。

• AWS アカウント ID。• 顧客がユーザーを識別するために使用する一意の External ID。詳細については、「AWS リソースへ

のアクセス権をサードパーティーに付与するときに外部 ID を使用する方法」を参照してください。• アプリケーションがアクセスする必要のある Amazon WorkDocs API のリスト。IAM ベースのポリシー

制御は、個々の API レベルでポリシーを許可または拒否することができる、詳細なコントロールです。Amazon WorkDocs API のリストについては、「Amazon WorkDocs API リファレンス」を参照してください。

次の手順は、クロスアカウントアクセスのための IAM の設定に含まれるステップについて説明します。

IAM でクロスアカウントアクセスを設定するには

1. Amazon WorkDocs API アクセス許可ポリシーを作成し、WorkDocsAPIReadOnly ポリシーとします。

2. Amazon WorkDocs サイトをホスティングする AWS アカウントの IAM コンソールで、新しいロールを作成します。

a. AWS マネジメントコンソール にサインインし、IAM コンソール(https://console.aws.amazon.com/iam/)を開きます。

b. コンソールのナビゲーションペインで [Roles] をクリックし、[Create New Role] をクリックします。

c. [Role name (ロール名)] ボックスにそのロールの目的を見分けやすくするロール名を入力します。たとえば、workdocs_app_role です。ロール名は AWS アカウント内で一意でなければなりません。ロール名を入力したら、[Next step] をクリックします。

d. [Select Role Type] ページで、[Role for Cross-Account Access] セクションを選択し、作成するロールのタイプを選択します。

• お客様がユーザーアカウントとリソースアカウントの両方の管理者であるか、両方のアカウントが同じ会社に属している場合は、[Provide access between AWS accounts you own] を選択します。このオプションは、ユーザー、ロール、アクセスされるリソースがすべて同じアカウントに属している場合にも選択します。

• お客様が Amazon WorkDocs サイトを所有するアカウントの管理者であり、アプリケーション開発者アカウントに属しているユーザーにアクセス許可を付与する必要がある場合は、

11

Page 15: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドIAM ロールを割り当てるための

アクセス許可を開発者に付与する

[Provide access between your AWS account and a third-party AWS account] を選択します。このオプションでは、お客様は、第三者によって提供される外部 ID を指定して、第三者がロールを使用してお客様のリソースにアクセスできる環境に対して、管理性を強化する必要があります。詳細については、「AWS リソースへのアクセス権を第三者に付与するときに外部 ID を使用する方法」を参照してください。

e. 次のページで、リソースへのアクセスを付与する AWS アカウント ID を指定し、サードパーティーによるアクセスがあった場合に備えて [外部 ID] も入力します。

f. [Next Step (次のステップ)] をクリックして、ポリシーをアタッチします。3. [Attach Policy (ポリシーのアタッチ)] ページで、以前に作成された Amazon WorkDocs API アクセス

許可ポリシーを検索して、ポリシーの横にあるボックスをオンにし、[Next Step (次のステップ)] をクリックします。

4. 詳細を確認し、今後の参照用にロール ARN をコピーして、[Create Role (ロールの作成)] をクリックしてロールの作成を完了します。

5. ロール ARN を開発者と共有します。ロール ARN の例を以下に示します。

arn:aws:iam::AWS-ACCOUNT-ID:role/workdocs_app_role

Amazon WorkDocs 顧客により与えられた IAMロールを割り当てるためのアクセス許可を開発者に付与する

開発者は、管理者 AWS アカウントでは、ロールを切り替えるユーザーアクセス権限を付与し、新しいポリシーを作成することで、ユーザーにアタッチします。

ロールを引き受けるアクセス権限をユーザーに付与するポリシーには、次の例に示すようにsts:AssumeRole アクションの Allow 効果を伴うステートメントおよび Resource エレメントのロールの Amazon リソースネーム (ARN) を含める必要があります。このポリシーを取得するユーザー (グルームメンバーまたは直接アタッチ) は、指定されたロールに切り替えることができます。

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::<aws_account_id>:role/ workdocs_app_role" }}

特定の Amazon WorkDocs インスタンスへのアクセスの制限

AWS アカウントに複数の Amazon WorkDocs サイトがあり、特定のサイトに API アクセスを許可する場合、条件要素を定義する必要があります。Condition エレメントは、ポリシーを実行するタイミングの条件を特定することができます。

条件要素の例を次に示します。

12

Page 16: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドIAM ユーザーまたはロールの通知の管理

"Condition": { "StringEquals": { "Resource.OrganizationId": "d-123456789c5" } }

上記のポリシーの条件により、ユーザーは ID d-123456789c5 の Amazon WorkDocs インスタンスにのみアクセスが許可されます。Amazon WorkDocs インスタンス ID は、組織 ID またはディレクトリ ID と呼ばれることもあります。

組織 ID は、ディレクトリ ID またはインスタンス ID と呼ばれることもあります。1 つのアカウントで 1 つ以上の Amazon WorkDocs サイトへのアクセスを制限するのに使用できます。詳細については、「特定のAmazon WorkDocs インスタンスへのアクセスの制限 (p. 12)」を参照してください。

次の手順を使用して、AWS コンソールから Amazon WorkDocs 組織 ID を取得できます。

組織 ID を取得するには

1. AWS Directory Service console ナビゲーションペインで [Directories (ディレクトリ)] を選択します。2. Amazon WorkDocs サイトに対応するディレクトリ ID は、そのサイトの組織 ID です。

IAM ユーザーまたはロールの通知の管理IAM 管理者は、Amazon WorkDocs コンソールを通して、IAM での通知を有効または無効にすることができます。

Note

通知 API へのアクセスを許可する明示的な許可ポリシーがユーザーまたはロールにアタッチされている場合でも、管理者は IAM コンソールを使用して、指定されたユーザーまたはロールのARN に対する通知を有効にする必要があります。ユーザーまたはロールの ARN に対して通知が明示的に有効にされている場合を除き、ユーザーまたはロールの認証情報を使用しているアプリケーションでは、通知を購読および受信するために CreateNotificationSubscription を呼び出すことはできません。

通知を有効化するには

1. Amazon WorkDocs コンソール(https://console.aws.amazon.com/zocalo/)を開きます。2. [Manage Your WorkDocs Sites (WorkDocs サイトの管理)] ページで、目的のディレクトリを選択し、

[Actions (アクション)]、[Manage Notifications (通知の管理)] の順に選択します。3. [Manage Notifications (通知の管理)] ページで、[Enable Notifications (通知を有効にする)] を選択しま

す。4. Amazon WorkDocs サイトから通知を受信できるようにするユーザーまたはロールの ARN を入力しま

す。

通知を無効化するには

1. Amazon WorkDocs コンソール(https://console.aws.amazon.com/zocalo/)を開きます。2. [Manage Your WorkDocs Sites (WorkDocs サイトの管理)] ページで、目的のディレクトリを選択し、

[Actions (アクション)]、[Manage Notifications (通知の管理)] の順に選択します。3. [Manage Notifications (通知の管理)] ページで、通知を無効にする ARN を選択し、[Disable

Notifications (通知の無効化)] を選択します。

13

Page 17: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドアプリケーションの作成

ユーザーアプリケーションの認証とアクセスコントロール

Amazon WorkDocs ユーザーレベルアプリケーションは、Amazon WorkDocs コンソールで登録、管理されます。開発者は、Amazon WorkDocs コンソールの My Applications ページでアプリケーションを登録する必要があります。各アプリケーションに対する一意の ID が提供されます。登録時に、開発者はリダイレクト URI を指定して、アクセストークンとアプリケーションスコープを受け取る必要があります。

アプリケーションは現在、登録されている同じ AWS アカウント内の Amazon WorkDocs サイトにのみアクセス可能です。

目次• アプリケーションの作成 (p. 14)• アプリケーションスコープ (p. 15)• 承認 (p. 15)• Amazon WorkDocs API の呼び出し (p. 16)

アプリケーションの作成Amazon WorkDocs 管理者として、次のステップを使用してアプリケーションを作成します。

アプリケーションを作成するには

1. Amazon WorkDocs コンソール(https://console.aws.amazon.com/zocalo/)を開きます。2. [My Applications (マイアプリケーション)]、[Create an Application (アプリケーションの作成)] の順に

選択します。3. 以下の値を入力します。

アプリケーション名

アプリケーションの名前。E メール

アプリケーションに関連付る E メールアドレス。アプリケーションの説明

アプリケーションの説明。[Redirect URIs (リダイレクト URI)]

Amazon WorkDocs がトラフィックをリダイレクトする場所。アプリケーションスコープ

アプリケーションに設定するスコープ (読み取りまたは書き込みのいずれか)。詳細については、「アプリケーションスコープ (p. 15)」を参照してください。

4. [Create] を選択します。

14

Page 18: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドアプリケーションスコープ

アプリケーションスコープAmazon WorkDocs は、次のアプリケーションスコープをサポートしています。

• Content Read (コンテンツ読み込み) (workdocs.content.read)。アプリケーションに以下の AmazonWorkDocs API へのアクセスを付与します。• Get*• Describe* (説明)

• Content Write (コンテンツ書き込み) (workdocs.content.write)。アプリケーションに以下のAmazon WorkDocs API へのアクセスを付与します。• 作成*• 更新*• 削除*• ジョブの開始*• 中止*• 追加*• 削除*

承認アプリケーション登録が完了したら、アプリケーションはすべての Amazon WorkDocs ユーザーに代わって許可をリクエストできます。これを行うには、アプリケーションは Amazon WorkDocs OAuth エンドポイントを参照して (https://auth.amazonworkdocs.com/oauth)、次のクエリパラメータを提供する必要があります。

• [Required (必須)] app_id — アプリケーションが登録されている場合に生成されるアプリケーションID。

• [Required (必須)] auth_type — リクエストの OAuth タイプ。サポートされている値はImplicitGrant です。

• [Required (必須)] redirect_uri — アプリケーションがアクセストークンを受信するよう登録されたリダイレクト URI。

• [Optional (オプション)] scopes — スコープのカンマ区切りのリスト。指定しない場合、登録時に選択されたスコープのリストが使用されます。

• [Optional (オプション)] state — アクセストークンとともに返される文字列。

アクセストークン取得のための OAuth フローを開始するためのサンプル GET リクエスト。

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. アプリケーションユーザーは、Amazon WorkDocs サイト名の入力を求められます。2. ユーザーは Amazon WorkDocs 認証ページにリダイレクトされます。認証情報を入力します。3. 認証に成功すると、ユーザーには、アプリケーションに Amazon WorkDocs へのアクセス許可を付与

するか、拒否するかを決める同意画面が表示されます。4. ユーザーが同意画面で Accept を選択すると、ブラウザは、クエリパラメータとしてのアクセストー

クンとリージョン情報とともに、アプリケーションのコールバック URL にリダイレクトされます。

15

Page 19: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドAmazon WorkDocs API の呼び出し

Amazon WorkDocs からのサンプル GET リクエスト。

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

アクセストークンに加えて、Amazon WorkDocs OAuth サービスは指定された Amazon WorkDocs サイトのクエリパラメータとして region も返します。外部アプリケーションでは、Amazon WorkDocs サービスエンドポイントを特定するために region パラメータを使用する必要があります。

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());}

16

Page 20: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドAmazon WorkDocs コンテンツマネージャの構築

Amazon WorkDocs コンテンツマネージャ

Amazon WorkDocs コンテンツマネージャーは、コンテンツを Amazon WorkDocs サイトにアップロードしたり、同サイトからダウンロードしたりする高レベルのユーティリティツールです。

トピック• Amazon WorkDocs コンテンツマネージャの構築 (p. 17)• ドキュメントのダウンロード (p. 18)• ドキュメントのアップロード (p. 18)

Amazon WorkDocs コンテンツマネージャの構築Amazon WorkDocs コンテンツマネージャは、管理アプリケーションおよびユーザーアプリケーションの両方に使用できます。

ユーザーアプリケーションの場合、開発者は匿名の AWS 認証情報と認証トークンを使用して AmazonWorkDocs コンテンツマネージャーを構築する必要があります。

管理アプリケーションの場合は、Amazon WorkDocs クライアントを AWS Identity and AccessManagement (IAM) 認証情報で初期化する必要があります。さらに、認証トークンは、後続の API コールでは省略する必要があります。

次のコードは、Java または C# を使用して、ユーザーアプリケーション用に Amazon WorkDocs コンテンツマネージャを初期化する方法を示します。

Java:

AWSStaticCredentialsProvider credentialsProvider = new AWSStaticCredentialsProvider(new AnonymousAWSCredentials());

AmazonWorkDocs client = AmazonWorkDocsClient.builder().withCredentials(credentialsProvider).withRegion("region").build();

ContentManager contentManager = ContentManagerBuilder.standard().withWorkDocsClient(client).withAuthenticationToken("token").build();

C#:

AmazonWorkDocsClient client = new AmazonWorkDocsClient(new AnonymousAWSCredentials(), "region");ContentManagerParams params = new ContentManagerParams{WorkDocsClient = client,AuthenticationToken = "token"};IContentManager workDocsContentManager = new ContentManager(param);

17

Page 21: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドドキュメントのダウンロード

ドキュメントのダウンロード開発者は、Amazon WorkDocs コンテンツマネージャーを使用して、ドキュメントの特定のバージョンまたは最新バージョンを Amazon WorkDocs からダウンロードすることができます。以下の例では、Java および C# を使用してドキュメントの特定のバージョンをダウンロードします。

Note

ドキュメントの最新バージョンをダウンロードするには、VersionId リクエストの構築時にGetDocumentStream を指定しないでください。

Java

ContentManager contentManager = ContentManagerBuilder.standard().withWorkDocsClient(client).withAuthenticationToken("auth-token").build();

// Download document.GetDocumentStreamRequest request = new GetDocumentStreamRequest();request.setDocumentId("document-id");request.setVersionId("version-id");

// stream contains the content of the document version.InputStream stream = contentManager.getDocumentStream(request).getStream();

C#

ContentManager contentManager = ContentManagerBuilder.standard().withWorkDocsClient(client).withAuthenticationToken("auth-token").build();

// Download document.GetDocumentStreamRequest request = new GetDocumentStreamRequest();request.setDocumentId("document-id");request.setVersionId("version-id");

// stream contains the content of the document version.InputStream stream = contentManager.getDocumentStream(request).getStream();

ドキュメントのアップロードAmazon WorkDocs コンテンツマネージャーには、Amazon WorkDocs サイトにコンテンツをアップロードするための API が用意されています。以下の例では、Java および C# を使用してドキュメントをアップロードします。

Java

File file = new File("file-path");InputStream stream = new FileInputStream(file);UploadDocumentStreamRequest request = new UploadDocumentStreamRequest();request.setParentFolderId("destination-folder-id");request.setContentType("content-type");request.setStream(stream);request.setDocumentName("document-name");contentManager.uploadDocumentStream(request);

C#

18

Page 22: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイドドキュメントのアップロード

var stream = new FileStream("file-path", FileMode.Open);

UploadDocumentStreamRequest uploadDocumentStreamRequest = new UploadDocumentStreamRequest(){ParentFolderId = "destination-id",DocumentName = "document-name",ContentType = "content-type",Stream = stream};

workDocsContentManager.UploadDocumentStreamAsync(uploadDocumentStreamRequest).Wait();

19

Page 23: Amazon WorkDocs - 開発者ガイド · • AWS サポートセンター – AWS サポートケースを作成および管理するためのハブです。フォーラム、技 術上のよくある質問、サービス状態ステータス、AWS

Amazon WorkDocs 開発者ガイド

AWS の用語集最新の AWS の用語については、『AWS General Reference』の「AWS の用語集」を参照してください。

20