API閘道功能支援要求格式身份驗證和授權服務整合模式輸出格式錯誤處理 IAM政策

RESTAPIs使用 Step Functions 建立API閘道

了解如何使用 Amazon API 閘道建立、發佈、維護HTTP和RESTAPIs監控 Step Functions。若要與API閘道整合，您可以在 Step Functions 中定義直接呼叫API閘道HTTP或API閘道REST端點的Task狀態，而無需撰寫程式碼或依賴其他基礎結構。Task狀態定義包括API呼叫的所有必要信息。您也可以選擇不同的授權方法。

若要瞭解如何整合 AWS 服務在 Step Functions 中，請參閱整合服務和。將參數傳遞給 Step Functions 數API中的服務

最佳化API閘道整合的主要功能

apigateway:invoke:在中沒有相等的 AWS SDK服務整合。而是，「最佳化API閘道」服務會直接呼叫API閘道端點。

API閘道功能支援

Step Functions API 閘道整合支援某些閘道功能，但不支援所有的API閘道功能。如需支援功能的詳細清單，請參閱下列內容。

Step Functions API 閘道RESTAPI和API閘道HTTPAPI整合均支援：
- 授權者：IAM（使用簽名版本 4），無身份驗證，Lambda 授權者（基於請求參數和基於令牌的自定義標題）
- API類型：區域
- API管理：API閘道API網域名稱、API階段、路徑、查詢參數、要求主體
由 Step Functions API 閘道HTTPAPI整合支援。不支援提供邊緣最佳化APIs選項的 Step Functions API 閘道RESTAPI整合。
Step Functions API 閘道整合不支援：
- 授權者：Amazon Cognito，原生開放 ID Connect/OAuth2.0，基於令牌的 Lambda 授權者的授權標頭
- API類型：私人
- API管理:自訂網域名稱

如需API閘道及其與的詳細資訊 HTTP RESTAPIs，請參閱下列內容。

Amazon API 閘道概念頁面。
RESTAPIs在API閘道開發人員指南中選擇HTTPAPIs和。

要求格式

當您建立Task狀態定義時，Step Functions 會驗證參數、建置執行呼叫所URL需的項目，然後呼叫. API 響應包括狀HTTP態碼，標題和響應主體。請求格式同時具有必要和可選參數。

必要的請求參數

ApiEndpoint
- 類型：String
- API閘道的主機名稱URL。格式是 <API ID>.execute-api.<region>.amazonaws.com。
  
  APIID 只能包含下列英數字元的組合：0123456789abcdefghijklmnopqrstuvwxyz
Method
- 類型：Enum
- 該HTTP方法，它必須是下列之一：
  - GET
  - POST
  - PUT
  - DELETE
  - PATCH
  - HEAD
  - OPTIONS

可選請求參數

Headers
- 類型：JSON
- HTTP標頭允許與同一個鍵相關聯的值的列表。
Stage
- 類型：String
- 在API閘道中部署到的階段名稱。API對於使用$default舞台的任何人來HTTPAPI說，它都是可選的。
Path
- 類型：String
- 附加在API端點之後的路徑參數。
QueryParameters
- 類型：JSON
- 查詢字串只允許與相同索引鍵相關聯的值清單。
RequestBody
- 類型：JSON 或 String。
- 請HTTP求主體。它的類型可以是一個JSON對象或String。 RequestBody僅支援PATCHPOST、和PUTHTTP方法。
AllowNullValues
- 類型：BOOLEAN— 預設值：false
- 使用預設設定時，請求輸入狀態下的任何 null 值都不會傳送至您的API. 在下列範例中，除非在狀態機器定義中設定為，否AllowNullValues則category欄位不會包含true在要求中。
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "category": null
    }
}
```
  注意
  默認情況下，在請求輸入狀態下具有 null 值的字段將不會發送到您的API. 您可以API通過true在狀態機定義中將設置為AllowNullValues來強制將 null 值發送到您的。
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閘道。


{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke", 
    "Parameters": {
        "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"
    } 
}

身份驗證和授權

您可以使用下列驗證方法：

無授權：無需授權方法即可API直接呼叫。
IAM角色：使用此方法，Step Functions 假定狀態機的作用，簽署與簽名版本 4（SIGv4）的請求，然後調用API.
資源策略：Step Functions 會驗證要求，然後呼叫. API 您必須將資源策略附加至指API定下列項目的：
1. 將呼叫API閘道的狀態機器。
  
  重要
  您必須指定狀態機器以限制對其的存取。如果您不這樣做，則任何使用資源策略驗證來驗證其 API Gateway 請求的狀態機器都API將被授予存取權。
2. 該 Step Functions 是調用API網關：的服務"Service": "states.amazonaws.com"。
3. 您要存取的資源，包括：
  - 所以此 region.
  - 所以此 account-id 在指定的區域中。
  - 所以此 api-id.
  - 所以此 stage-name.
  - 所以此 HTTP-VERB （方法）。
  - 所以此 resource-path-specifier.
如需資源策略的範例，請參閱 IAMStep Functions 和API閘道的政策。

如需有關資源格式的詳細資訊，請參閱《閘道開發人員指南》API中的API閘道執行權限的資源格式。API

注意
資源策略僅支援 RESTAPI.

服務整合模式

API閘道整合支援兩種服務整合模式：

請求回應，這是默認的集成模式。它可以讓 Step Functions 進展到接收HTTP響應後立即下一步。

使用任務令牌等待回調(.waitForTaskToken)，等待直到返回帶有有效負載的任務令牌。要使用該.waitForTaskToken模式，請附加。 waitForTask標記到任務定義的「資源」字段末尾，如以下示例所示：


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

輸出格式

提供了以下輸出參數：

名稱	Type	描述
`ResponseBody`	`JSON` 或 `String`	API呼叫的回應主體。
`Headers`	`JSON`	響應頭。
`StatusCode`	`Integer`	回應的HTTP狀態碼。
`StatusText`	`String`	響應的狀態文本。

一個示例響應：


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

錯誤處理

發生錯誤時，會傳回 error ANDcause，如下所示：

如果HTTP狀態碼可用，則會以格式傳回錯誤ApiGateway.<HTTP Status Code>。
如果HTTP狀態碼不可用，則會以格式傳回錯誤ApiGateway.<Exception>。

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

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


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

注意

的狀態碼2XX表示成功，且不會傳回任何錯誤。所有其他狀態碼或拋出的異常將導致錯誤。

IAM致電 Amazon API 網關的政策

下面的示例模板顯示如何 AWS Step Functions 根據狀態機器定義中的資源產生IAM策略。如需詳細資訊，請參閱 Step Functions 式如何為整合式服務產生IAM原則和探索 Step Functions 中的服務整合模式。

資源：


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

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


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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

整合最佳化服務

Amazon Athena