教學課程：建立RESTAPI為 Amazon S3 代理 - Amazon API Gateway
設IAM定API要叫用 Amazon S3 動作的許可建立API資源來代表 Amazon S3 資源公開一個API方法以列出調用者的 Amazon S3 存儲桶公開訪問 Amazon S3 存儲桶的API方法公開存取儲存貯體中 Amazon S3 物件的API方法

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

教學課程：建立RESTAPI為 Amazon S3 代理

作為展示使用RESTAPI中API閘道代理 Amazon S3 的範例，本節說明如何建立和設定RESTAPI以公開下列 Amazon S3 操作：

您可能想要將範例匯入API為 Amazon S3 代理伺服器，如中所示以 Amazon S3 代理的API形式開啟範例API定義。此範例包含更多已公開的方法。如需如何API使用「開啟」API 定義匯入的指示，請參閱RESTAPIs使用 API「在API閘道開啟」開發。

注意

若要將API閘道API與 Amazon S3 整合，您必須選擇同時提供API閘道和 Amazon S3 服務的區域。如需區域可用性的資訊，請參閱 Amazon API 閘道端點和配額。

主題

設IAM定API要叫用 Amazon S3 動作的許可

若要允許叫用 Amazon S3 動作，您必須將適當的IAM政策附加到IAM角色。API

若要建立服 AWS 務代理執行角色

  1. 登入 AWS Management Console 並開啟IAM主控台，位於https://console.aws.amazon.com/iam/。

  2. 選擇角色。

  3. 選擇建立角色。

  4. 在 [選取信任的實體類型] 下選擇 [AWS 服務]，然後選取 [API閘道]，然後選取 [允許API閘道將記錄檔推送至 CloudWatch 記錄

  5. 選擇下一步，然後選擇下一步。

  6. 針對角色名稱，輸入 APIGatewayS3ProxyPolicy，然後選擇建立角色。

  7. 在角色清單中，選擇您剛剛建立的角色。您可能需要捲動或使用搜尋列來尋找該角色。

  8. 針對選取的角色，選取 許可 索引標籤。

  9. 在下拉式清單中，選擇 連接政策。

  10. 在搜尋列中輸入 AmazonS3FullAccess，並選擇新增許可。

    注意

    本教學課程為了簡單起見，使用受管理政策。最佳作法是建立自己的IAM原則，以授與所需的最低權限。

  11. 請注意新創建的角色 ARN，您將在以後使用它。

建立API資源來代表 Amazon S3 資源

您可以使用API的根 (/) 資源做為已驗證呼叫者 Amazon S3 儲存貯體的容器。您也可以建立Folder和Item資源來分別代表特定的 Amazon S3 儲存貯體和特定的 Amazon S3 物件。資料夾名稱和物件索引鍵會由呼叫者以路徑參數的形式指定為要求URL的一部分。

注意

當訪問對象鍵包含/或任何其他特殊字符的對象時，需要對字符URL進行編碼。例如，test/test.txt 應編碼為 test%2Ftest.txt。

若要建立公開 Amazon S3 服務功能的API資源

  1. 在同一個 AWS 區域 你創建你的 Amazon S3 存儲桶，創建一個API命名的 MyS3。這API是根資源 (/) 代表 Amazon S3 服務。在此步驟中，您會另外建立兩個資源 /{folder} 和 /{item}。

  2. 選擇建立資源。

  3. 讓代理資源保持關閉。

  4. 針對資源路徑，選取 /。

  5. 針對資源名稱，輸入 {folder}。

  6. 保持不勾選 CORS(跨來源資源共用)。

  7. 選擇建立資源。

  8. 選取 /{folder} 資源，然後選擇建立資源。

  9. 使用上述步驟建立名為 {item} 的 /{folder} 子資源。

    您的最終API應該類似於以下內容：

    創建一個API在API網關作為 Amazon S3 代理

公開一個API方法以列出調用者的 Amazon S3 存儲桶

取得呼叫者的 Amazon S3 儲存貯體清單涉及在 Amazon S3 上叫用GET服務動作。在API根資源 (/) 上，建立方GET法。設定與 Amazon S3 整合的GET方法，如下所示。

若要建立和初始化API的GET /方法

  1. 選取 / 資源，然後選擇建立方法。

  2. 對於方法類型，選取GET。

  3. 針對整合類型，選取 AWS 服務。

  4. 在中 AWS 區域，選取您 AWS 區域 在哪裡建立 Amazon S3 儲存貯體。

  5. 針對 AWS 服務，選取 Amazon Simple Storage Service。

  6. 讓 AWS 子網域保持空白。

  7. 對於「HTTP方法」，請選取GET。

  8. 針對動作類型，選取使用路徑覆寫。

    使用路徑覆寫時，API閘道會將用戶端請求作為對應的 Amazon S3 路RESTAPI徑樣式請求轉送至 Amazon S3，其中 Amazon S3 資源由模式的資源路徑表示。s3-host-name/bucket/keyAPI閘道會設定s3-host-name指定的用戶端，bucket並key從用戶端傳送至 Amazon S3。

  9. 針對路徑覆寫，輸入 /。

  10. 對於執行角色，請輸入ARN的角色APIGatewayS3ProxyPolicy。

  11. 選擇 [方法要求設定]。

    您可以使用方法請求設置來控制誰可以調用您的API.

  12. 針對授權，從下拉式功能表中選取 AWS_IAM。

    宣告方法回應類型

  13. 選擇建立方法。

此設定會整合前端 GET https://your-api-host/stage/ 請求與後端 GET https://your-s3-host/。

為了API向調用者正確返回成功的響應和異常，請在方法響應中聲明 200，400 和 500 響應。您可以使用 200 個回應的預設對應，以便未在此處宣告之狀態碼的後端回應作為 200 個回應傳回給呼叫者。

宣告 GET / 方法的回應類型

  1. 在方法回應索引標籤上的回應 200 下，選擇編輯。

  2. 選擇新增標頭，然後執行下列動作：

    1. 針對標頭名稱，輸入 Content-Type。

    2. 選擇新增標頭。

    重複這些步驟以建立 Timestamp 標頭和 Content-Length 標頭。

  3. 選擇 Save (儲存)。

  4. 在方法回應索引標籤上的方法回應下，選擇建立回應。

  5. 如需HTTP狀態碼，請輸入 400。

    您未針對此回應設定任何標頭。

  6. 選擇 Save (儲存)。

  7. 重複以下步驟以建立 500 回應。

    您未針對此回應設定任何標頭。

由於 Amazon S3 的成功整合回應會以XML承載形式傳回儲存貯體清單，且API閘道的預設方法回應會傳回JSON承載，因此您必須將後端 Content-Type 標頭參數值對應至前端對應項目。否則，當響應主體實際上是一個XML字符串時，客戶端將收到application/json內容類型。下列程序示範如何設定此項目。此外，您還希望向客戶端顯示其他頭參數，例如日期和內容長度。

設置GET/方法的響應頭映射

  1. 在整合回應索引標籤上，於預設 - 回應下，選擇編輯。

  2. 針對 Content-Length 標頭，輸入 integration.response.header.Content-Length 作為對應值。

  3. 針對 Content-Type 標頭，輸入 integration.response.header.Content-Type 作為對應值。

  4. 針對時間戳記標頭，輸入 integration.response.header.Date 作為對應值。

  5. 選擇 Save (儲存)。結果應類似以下內容：

    將整合回應標頭對應至方法回應標頭

  6. 在整合回應索引標籤上的整合回應下，選擇建立回應。

  7. 對於HTTP狀態正則表達式，輸入4\d{2}。這將所有 4xx HTTP 響應狀態碼映射到方法響應。

  8. 針對方法回應狀態碼，選取 400。

  9. 選擇建立。

  10. 重複下列步驟，為 500 方法回應建立整合回應。對於HTTP狀態正則表達式，輸入5\d{2}。

作為一個好的做法，您可以測試到API目前為止配置的。

測試 GET / 方法

  1. 選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

  2. 選擇測試。結果應如下圖所示：

    測試API根GET值區結果

公開訪問 Amazon S3 存儲桶的API方法

若要使用 Amazon S3 儲存貯體，您可以公開/{資料夾} 資源上的GET方法以列出儲存貯體中的物件。這些說明與「公開一個API方法以列出調用者的 Amazon S3 存儲桶」中所述的說明類似。有關更多方法，您可以API在此處導入示例以 Amazon S3 代理的API形式開啟範例API定義。

若要公開資料夾資源上的GET方法

  1. 選取 /{folder} 資源，然後選擇建立方法。

  2. 對於方法類型，選取GET。

  3. 針對整合類型，選取 AWS 服務。

  4. 在中 AWS 區域，選取您 AWS 區域 在哪裡建立 Amazon S3 儲存貯體。

  5. 針對 AWS 服務，選取 Amazon Simple Storage Service。

  6. 讓 AWS 子網域保持空白。

  7. 對於「HTTP方法」，請選取GET。

  8. 針對動作類型，選取使用路徑覆寫。

  9. 針對路徑覆寫，輸入 {bucket}。

  10. 對於執行角色，請輸入ARN的角色APIGatewayS3ProxyPolicy。

  11. 選擇建立方法。

您可以在 Amazon S3 端點中設定{folder}路徑參數URL。您需要將方法請求的 {folder} 路徑參數對應至整合請求的 {bucket} 路徑參數。

將 {folder} 對應至 {bucket}

  1. 在整合請求索引標籤上，於整合請求設定下，選擇編輯。

  2. 選擇URL路徑參數，然後選擇 [新增路徑參數]。

  3. 針對名稱，輸入 bucket。

  4. 對於對應來源，輸入 method.request.path.folder。

  5. 選擇 Save (儲存)。

現在，您測試您的API.

測試 /{folder} GET 方法。

  1. 選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

  2. 在路徑下，針對資料夾，輸入儲存貯體的名稱。

  3. 選擇 測試。

    測試結果將包含儲存貯體中的物件清單。

    測試建立 Amazon S3 儲存貯體的GET方法。

公開存取儲存貯體中 Amazon S3 物件的API方法

Amazon S3 支援GET、DELETEHEADOPTIONS、POST和PUT動作來存取和管理指定儲存貯體中的物件。在本教學課程中，您會在 {folder}/{item} 資源上公開 GET 方法，以從儲存貯體取得映像。如需{folder}/{item}資源的更多應用程式，請參閱範例API以 Amazon S3 代理的API形式開啟範例API定義。

公開項目資源上的GET方法

  1. 選取 /{item} 資源，然後選擇建立方法。

  2. 對於方法類型，選取GET。

  3. 針對整合類型，選取 AWS 服務。

  4. 在中 AWS 區域，選取您 AWS 區域 在哪裡建立 Amazon S3 儲存貯體。

  5. 針對 AWS 服務，選取 Amazon Simple Storage Service。

  6. 讓 AWS 子網域保持空白。

  7. 對於「HTTP方法」，請選取GET。

  8. 針對動作類型，選取使用路徑覆寫。

  9. 針對路徑覆寫，輸入 {bucket}/{object}。

  10. 對於執行角色，請輸入ARN的角色APIGatewayS3ProxyPolicy。

  11. 選擇建立方法。

您可以在 Amazon S3 端點中設定{folder}和{item}路徑參數URL。您需要將方法請求的 路徑參數對應至整合請求的 路徑參數。

請於本步驟執行以下操作：

  • 將方法請求的 {folder} 路徑參數對應至整合請求的 {bucket} 路徑參數。

  • 將方法請求的 {item} 路徑參數對應至整合請求的 {object} 路徑參數。

將 {folder} 對應至 {bucket} 並將 {item} 對應至 {object}

  1. 在整合請求索引標籤上，於整合請求設定下，選擇編輯。

  2. 選擇URL路徑參數。

  3. 選擇新增路徑參數。

  4. 針對名稱，輸入 bucket。

  5. 對於對應來源，輸入 method.request.path.folder。

  6. 選擇新增路徑參數。

  7. 針對名稱，輸入 object。

  8. 對於對應來源，輸入 method.request.path.item。

  9. 選擇 Save (儲存)。

測試 /{folder}/{object} GET 方法。

  1. 選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

  2. 在路徑下，針對資料夾，輸入儲存貯體的名稱。

  3. 在路徑下，針對項目，輸入項目的名稱。

  4. 選擇測試。

    回應內文會包含該項目的內容。

    測試建立 Amazon S3 儲存貯體的GET方法。

    請求會正確地傳回 (「你好世界」) 的純文字做為指定檔案 (test.txt) 在指定的 Amazon S3 儲存貯體 (amzn-s3-示範儲存貯體) 中的內容。

要下載或上傳二進製文件，在 API Gateway 中被認為是 utf-8 編碼JSON內容以外的任何內容，需要額外的API設置。這概述如下：

從 S3 下載或上傳二進位檔案

  1. 將受影響檔案的媒體類型註冊到API的 binaryMediaTypes。您可以在主控台中執行這項操作：

    1. 選擇的API設定API。

    2. 在二進位媒體類型下，選擇管理媒體類型。

    3. 選擇新增二進位媒體類型，然後輸入所需的媒體類型，例如 image/png。

    4. 選擇儲存變更來儲存設定。

  2. 將 Content-Type (進行上傳) 和 (或) Accept (進行下載) 標頭新增至方法請求，以要求用戶端指定所需的二進位媒體類型，並將其對應至整合請求。

  3. 在整合請求 (進行上傳) 和整合回應 (進行下載) 中，將 Content Handling (內容處理) 設定為 Passthrough。請確定未定義受影響內容類型的對應範本。如需詳細資訊，請參閱整合傳遞行為和選取VTL對應範本。

承載大小上限為 10 MB。請參閱API 用於設定和執行 的閘道配額 REST API。

確定 Amazon S3 上的檔案具有新增為檔案中繼資料的正確內容類型。針對可串流媒體內容，Content-Disposition:inline 也可能需要新增至中繼資料。

如需API閘道中二進位支援的詳細資訊，請參閱API閘道中的內容類型轉換。