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

# 使用 Step Functions 建立 API Gateway REST APIs
<a name="connect-api-gateway"></a>

了解如何使用 Amazon API Gateway 透過 Step Functions 建立、發佈、維護和監控 HTTP 和 REST APIs。若要與 API Gateway 整合，您可以在 Step Functions 中定義直接呼叫 API Gateway HTTP 或 API Gateway REST 端點`Task`的狀態，而無需撰寫程式碼或依賴其他基礎設施。`Task` 狀態定義包含 API 呼叫的所有必要資訊。您也可以選取不同的授權方法。

若要了解如何在 Step Functions 中整合 AWS 服務，請參閱 [整合 服務](integrate-services.md)和 [在 Step Functions 中將參數傳遞至服務 API](connect-parameters.md)。

**Optimized API Gateway 整合的主要功能**  
`apigateway:invoke:` SDK AWS 服務整合中沒有同等項目。反之，最佳化 API Gateway 服務會直接呼叫您的 API Gateway 端點。

## API Gateway 功能支援
<a name="connect-api-gateway-support"></a>

Step Functions API Gateway 整合支援部分但並非所有 API Gateway 功能。如需支援功能的詳細清單，請參閱以下內容。
+ Step Functions API Gateway REST API 和 API Gateway HTTP API 整合都支援：
  + **授權方**：IAM （使用 [Signature 第 4 版](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html))、No Auth、Lambda 授權方 （以 request-parameter 為基礎，以字符為基礎，具有自訂標頭）
  + **API 類型**：區域
  + **API 管理**：API Gateway API 網域名稱、API 階段、路徑、查詢參數、請求內文
+ Step Functions API Gateway HTTP API 整合支援。不支援為 Edge 最佳化 API 提供 選項的 Step Functions API Gateway REST APIs 整合。
+ Step Functions API Gateway 整合不支援：
  +  **授權方**：Amazon Cognito、原生開放 ID Connect / OAuth 2.0、權杖型 Lambda 授權方的授權標頭 
  +  **API 類型**：私有 
  +  **API 管理**：自訂網域名稱 

如需 API Gateway 及其 HTTP 和 REST APIs的詳細資訊，請參閱以下內容。
+  [Amazon API Gateway 概念](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html)頁面。
+  [在 APIs開發人員指南中選擇 HTTP APIs和 REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) API。

## 要求格式
<a name="connect-api-gateway-requests"></a>

當您建立`Task`狀態定義時，Step Functions 會驗證參數、建置必要的 URL 來執行呼叫，然後呼叫 API。回應包含 HTTP 狀態碼、標頭和回應內文。請求格式同時具有必要和選用參數。

### 必要的請求參數
<a name="connect-api-gateway-requests-required"></a>
+ `ApiEndpoint`
  + 類型：`String`
  + API Gateway URL 的主機名稱。格式是 `<API ID>.execute-api.region.amazonaws.com`。

    API ID 只能包含下列英數字元的組合： `0123456789abcdefghijklmnopqrstuvwxyz`
+ `Method`
  + 類型：`Enum`
  + HTTP 方法，必須是下列其中一項：
    + `GET`
    + `POST`
    + `PUT`
    + `DELETE`
    + `PATCH`
    + `HEAD`
    + `OPTIONS`

### 選用請求參數
<a name="connect-api-gateway-requests-optional"></a>
+ `Headers`
  + 類型：`JSON`
  + HTTP 標頭允許與相同金鑰相關聯的值清單。
+ `Stage`
  + 類型：`String`
  + 在 API Gateway 中部署 API 的階段名稱。任何使用 `$default`階段的 HTTP API 都是選用的。
+ `Path`
  + 類型：`String`
  + 在 API 端點之後附加的路徑參數。
+ `QueryParameters`
  + 類型：`JSON`
  + 查詢字串僅允許與相同索引鍵相關聯的值清單。
+ `RequestBody`
  + 類型：`JSON` 或 `String`。
  + HTTP 請求內文。其類型可以是`JSON`物件或 `String`。 `RequestBody`僅支援 `PATCH`、 `POST`和 `PUT` HTTP 方法。
+ `AllowNullValues`
  + 類型： `BOOLEAN` – 預設值： `false`
  + 使用預設設定時，請求輸入狀態中的任何 **null** 值**都不會**傳送至您的 API。在下列範例中， `category` 欄位**不會**包含在請求中，除非在您的狀態機器定義`true`中`AllowNullValues`設定為 。

    ```
    {
        "NewPet": {
            "type": "turtle",
            "price": 123,
            "category": null
        }
    }
    ```
**注意**  
根據預設，請求輸入狀態中具有 **null** 值的欄位**不會**傳送至您的 API。您可以在狀態機器定義`true`中將 `AllowNullValues`設定為 ，強制將 null 值傳送至您的 API。
+ `AuthType`
  + 類型：`JSON`
  + 身分驗證方法。預設方法是 `NO_AUTH`。允許的值為：
    + `NO_AUTH`
    + `IAM_ROLE`
    + `RESOURCE_POLICY`

    如需詳細資訊，請參閱**身分驗證和授權**。

**注意**  
基於安全考量，目前不允許下列 HTTP 標頭金鑰：  
字首為 `X-Forwarded`、 `X-Amz`或 的任何內容`X-Amzn`。
`Authorization`
`Connection`
`Content-md5`
`Expect`
`Host`
`Max-Forwards`
`Proxy-Authenticate`
`Server`
`TE`
`Transfer-Encoding`
`Trailer`
`Upgrade`
`Via`
`Www-Authenticate`

下列程式碼範例示範如何使用 Step Functions 叫用 API Gateway。

```
{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke", 
    "Arguments": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "GET", 
        "Headers": { 
            "key": ["value1", "value2"] 
        },
        "Stage": "prod",
        "Path": "bills",
        "QueryParameters": {
            "billId": ["123456"]
        },
        "RequestBody": {},
        "AuthType": "NO_AUTH"
    } 
}
```

## 身分驗證和授權
<a name="connect-api-gateway-auth"></a>

您可以使用下列身分驗證方法：
+ **無授權**：在沒有授權方法的情況下直接呼叫 API。
+ **IAM 角色**：使用此方法時，Step Functions 會擔任狀態機器的角色，使用 [Signature 第 4 版](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (SigV4) 簽署請求，然後呼叫 API。
+ **資源政策**：Step Functions 會驗證請求，然後呼叫 API。您必須將資源政策連接至指定下列項目的 API：

  1. 將叫用 API Gateway 的狀態機器。
**重要**  
您必須指定狀態機器，才能限制存取。如果沒有，則任何使用**資源政策**身分驗證來驗證其 API Gateway 請求的狀態機器都會獲得 API 的存取權。

  1. Step Functions 是呼叫 API Gateway 的服務：`"Service": "states.amazonaws.com"`。

  1. 您要存取的資源，包括：
     + *區域*。
     + 指定區域中的 *account-id*。
     + *api-id*。
     + *stage-name*。
     + *HTTP-VERB* （方法）。
     + *resource-path-specifier*。

  如需範例資源政策，請參閱 [Step Functions 和 API Gateway 的 IAM 政策](#api-gateway-iam)。

  如需資源格式的詳細資訊，請參閱[《 API Gateway 開發人員指南》中的在 API Gateway 中執行 API 的許可資源格式](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api)。
**注意**  
只有 REST API 才支援資源政策。

## 服務整合模式
<a name="connect-api-gateway-patterns"></a>

API Gateway 整合支援兩種服務整合模式：
+ [請求回應](connect-to-resource.md#connect-default)，這是預設整合模式。它可讓 Step Functions 在收到 HTTP 回應後立即進入下一個步驟。
+ [使用任務字符等待回呼](connect-to-resource.md#connect-wait-token) (`.waitForTaskToken`)，它會等待任務字符與承載一起傳回。若要使用 `.waitForTaskToken` 模式，請將 .waitForTaskToken 附加至任務定義的**資源**欄位結尾，如下列範例所示：

  ```
  {
      "Type": "Task", 
      "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", 
      "Arguments": {
          "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
          "Method": "POST", 
          "Headers": { 
              "TaskToken": "{% $states.context.Task.Token %}"
          },
          "Stage": "prod",
          "Path": "bills/add",
          "QueryParameters": {},
          "RequestBody": {
              "billId": "my-new-bill"
          },
          "AuthType": "IAM_ROLE"
      } 
  }
  ```

## 輸出格式
<a name="connect-api-gateway-output"></a>

提供下列輸出參數：


| 名稱 | 類型 | 說明 | 
| --- | --- | --- | 
| ResponseBody | JSON 或 String | API 呼叫的回應內文。 | 
| Headers | JSON | 回應標頭。 | 
| StatusCode | Integer | 回應的 HTTP 狀態碼。 | 
| StatusText | String | 回應的狀態文字。 | 

回應範例：

```
{
    "ResponseBody": {
        "myBills": []
    },
    "Headers": { 
        "key": ["value1", "value2"]
    }, 
    "StatusCode": 200,
    "StatusText": "OK" 
}
```

## 錯誤處理
<a name="connect-api-gateway-errors"></a>

發生錯誤時，`cause`會傳回 `error`和 ，如下所示：
+ 如果 HTTP 狀態碼可用，則會以 格式傳回錯誤`ApiGateway.<HTTP Status Code>`。
+ 如果 HTTP 狀態碼無法使用，則會以 格式傳回錯誤`ApiGateway.<Exception>`。

在這兩種情況下， `cause` 都會以字串傳回。

下列範例顯示發生錯誤的回應：

```
{
    "error": "ApiGateway.403", 
    "cause": "{\"message\":\"Missing Authentication Token\"}"
}
```

**注意**  
狀態碼 `2XX`表示成功，不會傳回任何錯誤。所有其他狀態碼或擲出的例外狀況都會導致錯誤。

## Amazon API Gateway 呼叫的 IAM 政策
<a name="api-gateway-iam"></a>

下列範例範本顯示 如何根據狀態機器定義中的資源 AWS Step Functions 產生 IAM 政策。如需詳細資訊，請參閱[Step Functions 如何為整合服務產生 IAM 政策](service-integration-iam-templates.md)及[探索 Step Functions 中的服務整合模式](connect-to-resource.md)。

*資源：*

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/GET/pets",
                "arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/POST/pets"
            ],
            "Effect": "Allow"
        }
    ]
}
```

下列程式碼範例顯示呼叫 API Gateway 的資源政策。

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "states.amazonaws.com"
            },
            "Action": "execute-api:Invoke",
            "Resource": "arn:aws:execute-api:us-east-1:123456789012:myApi-id/stage-name/HTTP-VERB/resource-path-specifier",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": [
                        "<SourceStateMachineArn>"
                    ]
                }
            }
        }
    ]
}
```