本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Amazon Quick Sight API 開發應用程式 您可以使用 AWS SDKs來存取專為您正在使用的程式設計語言或平台量身打造的 API，以管理部署的大部分層面。如需詳細資訊，請參閱 [AWS 開發套件](https://aws.amazon.com/tools/#SDKs)。 如需 API 操作的詳細資訊，請參閱 [Amazon Quick Sight API 參考](https://docs.aws.amazon.com/quicksight/index.html?id=docs_gateway)。 在您可以呼叫 Amazon Quick Sight API 操作之前，您需要連接到 IAM 身分的政策中的 `quicksight:operation-name` 許可。例如，若要呼叫 `list-users`，您必須具備 `quicksight:ListUsers` 許可。同樣的模式適用於所有操作。 如果您不確定必要的許可是什麼，可以嘗試進行呼叫。然後，用戶端會告訴您缺少的許可是什麼。您可以在許可原則的「資源」欄位中使用星號 (`*`)，而不指定明確的資源。但建議您盡可能限制每個許可。您可以使用 Amazon Quick Sight Amazon Resource Name (ARN) 識別符，在政策中指定或排除資源來限制使用者存取。 如需詳細資訊，請參閱下列內容： + [Amazon Quick Sight 的 IAM 政策範例](https://docs.aws.amazon.com/quicksight/latest/user/iam-policy-examples.html) + [動作、資源及條件索引鍵](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonquicksight.html) + [IAM JSON 政策元素](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) 若要擷取使用者或群組的 ARN，請對相關資源使用 `Describe` 操作。您也可以在 IAM 中新增條件，進一步限制某些情況下的 API 存取。例如，將 `User1`新增至 時`Group1`，主要資源是 `Group1`，因此您可以允許或拒絕存取特定群組，但您也可以使用 IAM Amazon Quick Sight 金鑰來新增條件`quicksight:UserName`，以允許或防止特定使用者新增至該群組。 以下是政策的範例。這表示只要新增至群組的使用者名稱不是 `user1`，連接此政策的呼叫者就能在任何群組上呼叫 `CreateGroupMembership` 操作。 ``` { "Effect": "Allow", "Action": "quicksight:CreateGroupMembership", "Resource": "arn:aws:quicksight:us-east-1:aws-account-id:group/default/*", "Condition": { "StringNotEquals": { "quicksight:UserName": "user1" } } } ``` ------ #### [ AWS CLI ] 下列程序說明如何透過 CLI 與 Amazon Quick Sight API AWS 操作互動。此說明內容已在 Bash 中進行過測試，但在其他命令列環境下應可得到同樣或類似的結果。 1. 在您的環境中安裝 AWS SDK。如需如何執行此操作的說明，請參閱 [AWS Command Line Interface](https://aws.amazon.com/cli/)。 1. 使用下列命令和後續指示來設定您的 AWS CLI 身分和區域。請使用具備適當許可的 IAM 身分或角色的登入資料。 ``` aws configure ``` 1. 發出下列命令，查看 Amazon Quick Sight SDK 說明： ``` aws quicksight help ``` 1. 若要取得如何使用特定 API 的詳細說明，請輸入其名稱，後面加上 help，例如： ``` aws quicksight list-users help ``` 1. 現在您可以呼叫 Amazon Quick Sight API 操作。此範例會傳回您帳戶中的 Amazon Quick Sight 使用者清單。 ``` aws quicksight list-users --aws-account-id aws-account-id --namespace default --region us-east-1 ``` ------ #### [ Java SDK ] 使用下列程序來設定與 Amazon Quick Sight 互動的 Java 應用程式。 1. 若要開始使用，請在 IDE 中建立 Java 專案。 1. 將 Amazon Quick Sight SDK 匯入您的新專案，例如： `AWSQuickSightJavaClient-1.11.x.jar` 1. 一旦您的 IDE 為 Amazon Quick Sight SDK 編製索引，您應該能夠新增匯入列，如下所示： ``` import com.amazonaws.services.quicksight.AmazonQuickSight; ``` 如果 IDE 未將其判別為有效語法，請確認您是否已匯入軟體開發套件。 1. 如同其他 AWS SDKs，Amazon Quick Sight SDK 需要外部相依性才能執行其許多函數。您必須下載依存項目並將之匯入同一專案。必要的依存項目如下： + `aws-java-sdk-1.11.402.jar` (AWS Java 開發套件和登入資料設定） — 請參閱[設定適用於 Java 的 AWS 開發套件 ](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-install.html) + `commons-logging-1.2.jar` – 請參閱 [ https://commons.apache.org/proper/commons-logging/download\$1logging.cgi ](https://commons.apache.org/proper/commons-logging/download_logging.cgi) + `jackson-annotations-2.9.6.jar`、`jackson-core-2.9.6.jar` 及 `jackson-databind-2.9.6.jar` – 請參閱 [ http://repo1.maven.org/maven2/com/fasterxml/jackson/core/ ](https://repo1.maven.org/maven2/com/fasterxml/jackson/core/) + `httpclient-4.5.6.jar`、`httpcore-4.4.10.jar` – 請參閱 [ https://hc.apache.org/downloads.cgi ](https://hc.apache.org/downloads.cgi) + `joda-time-2.1.jar` – 請參閱 [ https://mvnrepository.com/artifact/joda-time/joda-time/2.1 ](https://mvnrepository.com/artifact/joda-time/joda-time/2.1) 1. 現在，您已準備好建立 Amazon Quick Sight 用戶端。您可以使用能夠由用戶端與之通訊的預設公有端點，或是明確參考該端點。有多種方式可以提供您的 AWS 登入資料。以下範例介紹既直接又簡單的方法。底下的用戶端方法用於進行所有 API 呼叫： ``` private static AmazonQuickSight getClient() { final AWSCredentialsProvider credsProvider = new AWSCredentialsProvider() { @Override public AWSCredentials getCredentials() { // provide actual IAM access key and secret key here return new BasicAWSCredentials("access-key", "secret-key"); } @Override public void refresh() {} }; return AmazonQuickSightClientBuilder .standard() .withRegion(Regions.US_EAST_1.getName()) .withCredentials(credsProvider) .build(); } ``` 1. 現在，我們可以使用上述用戶端列出 Amazon Quick Sight 帳戶中的所有使用者。 **注意** 您必須提供用來訂閱 Amazon Quick Sight AWS 的帳戶 ID。這必須符合發起人身分 AWS 的帳戶 ID。目前不支援跨帳戶呼叫。此外，必要參數 `namespace` 應一律設為 *default*。 ``` getClient().listUsers(new ListUsersRequest() .withAwsAccountId("relevant_AWS_account_ID") .withNamespace("default")) .getUserList().forEach(user -> { System.out.println(user.getArn()); }); ``` 1. 若要查看所有可能的 API 操作及其使用的請求物件清單，您可以在 IDE 中的用戶端物件上**按一下 CTRL**，以檢視 Amazon Quick Sight 介面。或者，在 Amazon Quick Sight JavaClient JAR 檔案中的 `com.amazonaws.services.quicksight`套件中找到它。 ------ #### [ JavaScript (Node.js) SDK ] 使用下列程序來使用 Node.js 與 Amazon Quick Sight 互動。 1. 使用以下命令設定您的節點環境： + `npm install aws-sdk` + `npm install aws4 ` + `npm install request` + `npm install url` 1. 如需有關使用 AWS SDK 設定 Node.js 和設定登入資料的資訊，請參閱--> [適用於 JavaScript 的 AWS SDK SDK v2 的開發人員指南](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html)。 1. 使用以下程式碼範例測試您的設定。HTTPS 為必要項目。此範例會顯示 Amazon Quick Sight 操作的完整清單及其 URL 請求參數，後面接著您帳戶中的 Amazon Quick Sight 使用者清單。 ``` const AWS = require('aws-sdk'); const https = require('https'); var quicksight = new AWS.Service({ apiConfig: require('./quicksight-2018-04-01.min.json'), region: 'us-east-1', }); console.log(quicksight.config.apiConfig.operations); quicksight.listUsers({ // Enter your actual AWS account ID 'AwsAccountId': 'relevant_AWS_account_ID', 'Namespace': 'default', }, function(err, data) { console.log('---'); console.log('Errors: '); console.log(err); console.log('---'); console.log('Response: '); console.log(data); }); ``` ------ #### [ Python3 SDK ] 使用下列程序建立自訂建置`botocore`套件，以與 Amazon Quick Sight 互動。 1. 在 AWS 目錄中為您的環境建立登入資料檔案。在 Linux/Mac 環境中，該檔案名為 \$1/.aws/credentials，其內容如下： ``` [default] aws_access_key_id = Your_IAM_access_key aws_secret_access_key = Your_IAM_secret_key ``` 1. 解壓縮 `botocore-1.12.10` 資料夾。將目錄切換到 `botocore-1.12.10`，然後進入 Python3 解譯器環境。 1. 回應將以字典物件的形式傳回。每次回應都會有 `ResponseMetadata` 項目，其中包含請求 ID 和回應狀態。其餘項目則視您所執行的操作類型而定。 1. 以下所示的範例應用程式將首先建立、刪除和列出群組，接著列出 Quicksight 帳戶中的使用者： ``` import botocore.session default_namespace = 'default' account_id = 'relevant_AWS_Account' session = botocore.session.get_session() client = session.create_client("quicksight", region_name='us-east-1') print('Creating three groups: ') client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1') client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2') client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3') print('Retrieving the groups and listing them: ') response = client.list_groups(AwsAccountId = account_id, Namespace=default_namespace) for group in response['GroupList']: print(group) print('Deleting our groups: ') client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1') client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2') client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3') response = client.list_users(AwsAccountId = account_id, Namespace=default_namespace) for user in response['UserList']: print(user) ``` ------ #### [ .NET/C\$1 SDK ] 使用下列程序來使用 C\$1 與 Amazon Quick Sight 互動。NET。此範例是由 Microsoft Visual Studio for Mac 所建構；視您的 IDE 及平台而定，說明內容可能略有不同。不過，程序應大致雷同。 1. 將 `nuget.zip` 檔案解壓縮到名為 `nuget` 的資料夾。 1. 在 Visual Studio 中建立新的**主控台應用程式**。 1. 在方案底下找出應用程式**相依性**，然後開啟內容功能表 (按滑鼠右鍵) 並選擇 **Add Packages (新增封裝)**。 1. 在來源清單中，選擇 **Configure Sources (設定來源)**。 1. 選擇 **Add (新增)**。然後將該來源命名為 `QuickSightSDK`。瀏覽至 `nuget` 資料夾並選擇 **Add Source (新增來源)**。 1. 選擇**確定**。然後，`QuickSightSDK`選取所有三個 Amazon Quick Sight 套件： + `AWSSDK.QuickSight` + `AWSSDK.Extensions.NETCore.Setup` + `AWSSDK.Extensions.CognitoAuthentication` 1. 按一下 **Add Package (新增封裝)**。 1. 複製以下範例應用程式並將其貼入您的主控台應用程式編輯器。 ``` using System; using Amazon.QuickSight.Model; using Amazon.QuickSight; namespace DotNetQuickSightSDKTest { class Program { private static readonly string AccessKey = "insert_your_access_key"; private static readonly string SecretAccessKey = "insert_your_secret_key"; private static readonly string AccountID = "AWS_account_ID"; private static readonly string Namespace = "default"; // leave this as default static void Main(string[] args) { var client = new AmazonQuickSightClient( AccessKey, SecretAccessKey, Amazon.RegionEndpoint.USEast1); var listUsersRequest = new ListUsersRequest { AwsAccountId = AccountID, Namespace = Namespace }; client.ListUsersAsync(listUsersRequest).Result.UserList.ForEach( user => Console.WriteLine(user.Arn) ); var listGroupsRequest = new ListGroupsRequest { AwsAccountId = AccountID, Namespace = Namespace }; client.ListGroupsAsync(listGroupsRequest).Result.GroupList.ForEach( group => Console.WriteLine(group.Arn) ); } } } ``` ------