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

# 在 API Gateway 中設定方法請求
<a name="api-gateway-method-settings-method-request"></a>

設定方法請求需要在建立 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 資源之後執行下列任務：

1.  建立新的 API 或選擇現有的 API [資源](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)實體。

1.  在新的或選擇的 API `Resource` 上，建立 API [方法](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html)資源 (也就是特定 HTTP 動詞)。這項作業可進一步分為下列子任務：
   +  將 HTTP 方法新增至方法請求
   +  設定請求參數
   +  定義請求本文的模型
   +  制定授權配置
   +  啟用請求驗證 

您可以使用下列方法來執行這些任務：
+  [API Gateway 主控台](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)
+  AWS CLI 命令 ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) 和 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html))
+  AWS SDK 函數 （例如，在 Node.js 中，[createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) 和 [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property))
+  API Gateway REST API ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) 與 [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html))。

**Topics**
+ [設定 API 資源](#setup-method-resources)
+ [設定 HTTP 方法](#setup-method-add-http-method)
+ [設定方法請求參數](#setup-method-request-parameters)
+ [設定方法請求模型](#setup-method-request-model)
+ [設定方法請求授權](#setup-method-request-authorization)
+ [設定方法請求驗證](#setup-method-request-validation)

## 設定 API 資源
<a name="setup-method-resources"></a>

在 API Gateway API 中，您可以將可定址的資源公開為 API [資源](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html)實體的樹狀目錄，其根資源 (`/`) 在階層的最上層。此根資源與 API 的基底 URL 相關，其中包含 API 端點與階段名稱。在 API Gateway 主控台中，此基底 URI 稱為 **Invoke URI (呼叫 URI)**，並會在部署 API 之後顯示在 API 的階段編輯器中。

API 端點可以是預設主機名稱或自訂網域名稱。預設主機名稱的格式如下：

```
{api-id}.execute-api.{region}.amazonaws.com
```

在此格式中，*\$1api-id\$1* 表示 API Gateway 所產生的 API 識別符。`{region}` 變數表示您在建立 API 時選擇的 AWS 區域 (例如 `us-east-1`)。自訂網域名稱是有效網際網路網域下的任何使用者易記名稱。例如，如果您已註冊網際網路網域 `example.com`，任何 `*.example.com` 都是有效的自訂網域名稱。如需詳細資訊，請參閱[建立自訂網域名稱](how-to-custom-domains.md)。

以 [PetStore 範例 API](api-gateway-create-api-from-example.md) 而言，根資源 (`/`) 會公開寵物店。`/pets` 資源表示寵物店中可用的寵物集合。`/pets/{petId}` 會公開指定識別符 (`petId`) 的個別寵物。`{petId}` 的路徑參數是請求參數的一部分。

若要設定 API 資源，您可以選擇現有資源作為其父系，然後在此父資源下建立子資源。您一開始會以根資源作為父系，然後將資源新增至此父系，再將另一項資源新增至此子資源作為新的父系，依此類推直到新增至其父識別符。然後，您可以將具名資源新增至父系。

以下 [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) 命令會擷取 API 的所有資源：

```
aws apigateway get-resources --rest-api-id apiId
```

在 PetStore 範例 API 中，輸出如下所示：

```
{
    "items": [
        {
            "path": "/pets", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "6sxz2j", 
            "pathPart": "pets", 
            "parentId": "svzr2028x8"
        }, 
        {
            "path": "/pets/{petId}", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "rjkmth", 
            "pathPart": "{petId}", 
            "parentId": "6sxz2j"
        }, 
        {
            "path": "/", 
            "id": "svzr2028x8"
        }
    ]
}
```

每個項目會列出資源的識別符 (`id`)、其直屬父系 (`parentId`) (根資源除外)，以及資源名稱 (`pathPart`)。根資源是特殊的，因為它沒有任何父系。選擇某個資源作為父資源之後，使用下列命令來新增子資源：

```
aws apigateway create-resource --rest-api-id apiId \
    --parent-id parentId \
    --path-part resourceName
```

例如，若要在 PetStore 網站上新增販售的寵物食品，請使用下列命令：

```
aws apigateway create-resource --rest-api-id a1b2c3 \
    --parent-id svzr2028x8 \
    --path-part food
```

輸出將如下所示：

```
{
    "path": "/food", 
    "pathPart": "food", 
    "id": "xdsvhp", 
    "parentId": "svzr2028x8"
}
```

### 使用代理資源來簡化 API 設定
<a name="api-gateway-proxy-resource"></a>

隨著業務成長，PetStore 擁有者可能會決定新增食品、玩具與其他寵物相關項目來進行促銷。為了支援此目的，您可以在根資源下新增 `/food`、`/toys` 與其他資源。在每個銷售類別下，您可能還想要新增更多資源，例如 `/food/{type}/{item}`、`/toys/{type}/{item}` 等。這可能會變得很冗長。如果您決定將中介層 `{subtype}` 新增至資源路徑，以將路徑階層變更為 `/food/{type}/{subtype}/{item}`、`/toys/{type}/{subtype}/{item}` 等，變更會中斷現有的 API 設定。為了避免這種情況，您可以使用 API Gateway [代理資源](api-gateway-set-up-simple-proxy.md)一次完全公開一組 API 資源。

API Gateway 會將代理資源定義為要在提交請求時指定之資源的預留位置。代理資源是由 `{proxy+}` 的特殊路徑參數來表示，通常稱為 Greedy 路徑參數。`+` 符號指出要附加的子資源。`/parent/{proxy+}` 預留位置代表符合 `/parent/*` 之路徑模式的任何資源。您可以使用任何字串作為 greedy 路徑參數名稱。

以下 [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) 命令會在根目錄 (`/{proxy+}`) 下建立代理資源：

```
aws apigateway create-resource --rest-api-id apiId \
    --parent-id rootResourceId \
    --path-part {proxy+}
```

輸出將如下所示：

```
{
    "path": "/{proxy+}", 
    "pathPart": "{proxy+}", 
    "id": "234jdr", 
    "parentId": "svzr2028x8"
}
```

在 `PetStore` API 範例中，您可以使用 `/{proxy+}` 來表示 `/pets` 與 `/pets/{petId}`。此代理資源也可以參考其他任何 (現有或是要新增的) 資源，例如 `/food/{type}/{item}`、`/toys/{type}/{item}` 等，或是 `/food/{type}/{subtype}/{item}`、`/toys/{type}/{subtype}/{item}` 等。後端開發人員會決定資源階層，而用戶端開發人員則負責了解此階層。API Gateway 只會將用戶端提交的任何項目傳遞到後端。

一個 API 可以有多個代理資源。例如，API 中允許下列代理資源，假設 `/parent/{proxy+}` 和 `/parent/{child}/{proxy+}` 不在相同父系層級。

```
/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}
```

當代理資源有非代理同層級資源時，則會從代理資源的顯示方式中排除這些同層級資源。在上述範例中，`/{proxy+}` 是指根資源下除了 `/parent[/*]` 資源以外的任何資源。換言之，對特定資源提出的方法請求，會優先於對資源階層中同層級之一般資源提出的方法請求。

下表顯示 API Gateway 如何將請求路由至 API `prod` 階段的下列資源。

```
ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog
```


| 請求 | 選取的路由 | 說明 | 
| --- | --- | --- | 
|  `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog`  |  `GET /pets/dog`  |  請求與此資源完全相符。  | 
|  `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats`  |  `GET /pets/{proxy+}`  |  `/pets/{proxy+}` greedy 路徑變數會擷取此請求。  | 
|  `GET https://api-id.execute-api.region.amazonaws.com/prod/animals`  |  `GET /{proxy+}`  |  `/{proxy+}` greedy 路徑變數會擷取此請求。  | 

代理資源不能有任何子資源。`{proxy+}` 後面的任何 API 資源是多餘且模棱兩可的。API 中不允許下列代理資源。

```
/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}
```

## 設定 HTTP 方法
<a name="setup-method-add-http-method"></a>

API 方法請求是由 API Gateway [方法](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html)資源所封裝。若要設定方法請求，您必須先具現化 `Method` 資源、設定至少一個 HTTP 方法，並在該方法上設定至少一種授權類型。

與代理資源密切相關的是，API Gateway 支援 HTTP 方法 `ANY`。此 `ANY` 方法代表要在執行階段提供的任何 HTTP 方法。它可讓您針對 `DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` 與 `PUT` 之所有支援的 HTTP 方法，使用單一 API 方法設定。

您也可以在非代理資源上設定 `ANY` 方法。透過將 `ANY` 方法與代理資源合併，您就可以對 API 的任何資源，取得所有支援之 HTTP 方法的單一 API 方法設定。此外，後端可繼續發展而不需要中斷現有的 API 設定。

 設定 API 方法之前，請考慮誰可以呼叫此方法。請根據您的方案設定授權類型。如需開放式存取，請將其設定為 `NONE`。若要使用 IAM 許可，請將授權類型設定為 `AWS_IAM`。若要使用 Lambda 授權方函數，請將此屬性設定為 `CUSTOM`。若要使用 Amazon Cognito 使用者集區，請將授權類型設定為 `COGNITO_USER_POOLS`。

以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令會使用 IAM 許可建立 `ANY` 動詞的方法請求，以控制其存取。

```
aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method ANY \
    --authorization-type AWS_IAM
```

若要使用不同的授權類型來建立 API 方法請求，請參閱「[設定方法請求授權](#setup-method-request-authorization)」。

## 設定方法請求參數
<a name="setup-method-request-parameters"></a>

方法請求參數可讓用戶端提供完成方法請求所需的輸入資料或執行內容。方法參數可以是路徑參數、標頭或查詢字串參數。設定方法請求時，您必須宣告必要的請求參數以提供給用戶端。對於非代理整合，您可以將這些請求參數轉換成與後端需求相容的格式。

例如，對於 `GET /pets/{petId}` 方法請求，`{petId}` 路徑變數是必要的請求參數。您可以在呼叫 AWS CLI的 `put-method` 命令時宣告此路徑參數，以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令會建立方法與必要的路徑參數：

```
aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id rjkmth \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.path.petId=true
```

如果不需要參數，您可以在 `false` 中將它設定為 `request-parameters`。例如，如果 `GET /pets` 方法使用選用的查詢字串參數 `type` 與選用的標頭參數 `age`，則您可以使用以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令來宣告這些參數：

```
aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.querystring.type=false,method.request.header.age=false
```

除了此縮寫格式之外，您還可以使用 JSON 字串來設定 `request-parameters` 值：

```
'{"method.request.querystring.type":false,"method.request.header.age":false}'
```

有了這項設定，用戶端就可依類型查詢寵物：

```
GET /pets?type=dog
```

 而且用戶端可以查詢哪些狗是幼犬，如下所示：

```
GET /pets?type=dog
age:puppy
```

如需如何將方法請求參數映射到整合請求參數的資訊，請參閱「[API Gateway 中 REST API 的整合](how-to-integration-settings.md)」。

## 設定方法請求模型
<a name="setup-method-request-model"></a>

若要讓 API 方法可接受承載中的輸入資料，您可以使用模型。模型是以 [JSON 結構描述草稿第 4 版](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04)來表示，並描述請求本文的資料結構。透過模型，用戶端可以判斷如何建構方法請求承載作為輸入。更重要的是，API Gateway 可使用模型來[驗證請求](api-gateway-method-request-validation.md)、[產生軟體開發套件](how-to-generate-sdk.md)，並初始化映射範本以在 API Gateway 主控台中設定整合。如需如何建立[模型](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html)的相關資訊，請參閱[了解資料模型](models-mappings-models.md)。

視內容類型而定，一個方法承載可能會有不同的格式。模型會針對已套用承載的媒體類型來編製索引。API Gateway 使用 `Content-Type` 請求標頭來確定內容類型。若要設定方法請求模型，請在呼叫 AWS CLI `put-method` 命令時，將`"media-type":"model-name"`格式的鍵值對新增至`requestModels`映射。

若要使用相同的模型，而不論內容類型為何，請指定 `$default` 為索引鍵。

例如，若要在 PetStore 範例 API 之 `POST /pets` 方法請求的 JSON 承載上設定模型，您可以使用以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令：

```
aws apigateway put-method \
    --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method POST \
    --authorization-type "NONE" \
    --request-models '{"application/json":"petModel"}'
```

在此範例中，`petModel` 是描述寵物之 [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) 資源的 `Model` 屬性值。實際結構描述定義會以 `schema` 資源之 [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) 屬性的 JSON 字串值表示。

 在 API 的 Java 開發套件或其他強型別開發套件中，輸入資料會轉換成衍生自結構描述定義的 `petModel` 類別。透過請求模型，所產生之開發套件中的輸入資料會轉換成衍生自預設 `Empty` 模型的 `Empty` 類別。在本例中，用戶端無法具現化正確的資料類別以提供必要的輸入。



## 設定方法請求授權
<a name="setup-method-request-authorization"></a>



 若要控制誰可以呼叫 API 方法，您可以在方法上設定[授權類型](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)。您可以使用此類型制定其中一個支援的授權方，包括 IAM 角色與政策 (`AWS_IAM`)、Amazon Cognito 使用者集區 (`COGNITO_USER_POOLS`) 或 Lambda 授權方 (`CUSTOM`)。

若要使用 IAM 許可來授權存取 API 方法，請將 `authorization-type` 輸入屬性設定為 **AWS\$1IAM**。在您設定此選項時，API Gateway 會根據發起人的憑證驗證發起人對要求的簽章。如果經驗證的使用者擁有呼叫方法的許可，則會接受請求。否則，請求會遭到拒絕，且發起人會收到未經授權的錯誤回應。除非發起人擁有呼叫 API 方法的許可，否則對方法的呼叫不會成功。以下 IAM 政策會向發起人授予呼叫在同一 AWS 帳戶中建立之任何 API 方法的許可：

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}
```

------

如需詳細資訊，請參閱[使用 IAM 許可權控制 REST API 的存取](permissions.md)。

目前，您只能將此政策授予 API 擁有者的 AWS 帳戶中的使用者、群組和角色。來自不同 的使用者只有在允許在 API 擁有者的 中擔任角色，並 AWS 帳戶 具有呼叫`execute-api:Invoke`動作的必要許可時， AWS 帳戶 才能呼叫 API 方法。如需跨帳戶許可的資訊，請參閱[使用 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)。

您可以使用 AWS AWS CLI開發套件或 REST API 用戶端，例如 [Postman](https://www.postman.com/)，其會實作 [Signature 第 4 版 (SigV4) 簽署](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html)。

若要使用 Lambda 授權方來授權對 API 方法的存取，請將 `authorization-type` 輸入屬性設定為 `CUSTOM`，並將 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) 輸入屬性設定為已存在之 Lambda 授權方的 [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) 屬性值。參考的 Lambda 授權方可以是 `TOKEN` 或 `REQUEST` 類型。如需建立 Lambda 授權方的資訊，請參閱[使用 API Gateway Lambda 授權方](apigateway-use-lambda-authorizer.md)。

若要使用 Amazon Cognito 使用者集區來授權對 API 方法的存取，請將 `authorization-type` 輸入屬性設定為 `COGNITO_USER_POOLS`，並將 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) 輸入屬性設定為已建立之 `COGNITO_USER_POOLS` 授權方的 [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) 屬性值。如需有關建立 Amazon Cognito 使用者集區授權方的資訊，請參閱[使用 Amazon Cognito 使用者集區做為授權方，藉以控制對 REST API 的存取](apigateway-integrate-with-cognito.md)。

## 設定方法請求驗證
<a name="setup-method-request-validation"></a>

您可以在設定 API 方法請求時啟用請求驗證。您必須先建立[請求驗證程式](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)。以下 [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) 命令會建立僅限內文的請求驗證程式。

```
aws apigateway create-request-validator \
    --rest-api-id 7zw9uyk9kl \
    --name bodyOnlyValidator \
    --validate-request-body  \
    --no-validate-request-parameters
```

輸出將如下所示：

```
{
    "validateRequestParameters": false, 
    "validateRequestBody": true, 
    "id": "jgpyy6", 
    "name": "bodyOnlyValidator"
}
```

只要使用此請求驗證程式，您就可以在設定方法請求時使用請求驗證。以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令會建立方法請求，以要求傳入的請求內文符合 `PetModel`，並且具有兩個非必要的請求參數：

```
aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl \
    --resource-id xdsvhp \
    --http-method PUT \
    --authorization-type "NONE" \
    --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \ 
    --request-models '{"application/json":"petModel"}' \
    --request-validator-id jgpyy6
```

若要將請求參數納入請求驗證中，您必須將請求驗證程式的 `validateRequestParameters` 設定為 `true`，並將 `put-method` 命令中的特定請求參數設定為 `true`。