本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# ApiAuth
設定授權以控制對 API Gateway API 的存取。
如需使用 設定存取權的詳細資訊和範例， AWS SAM 請參閱 [使用 AWS SAM 範本控制 API 存取](serverless-controlling-access-to-apis.md)。
## 語法
若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。
### YAML
```
AddApiKeyRequiredToCorsPreflight: Boolean
[AddDefaultAuthorizerToCorsPreflight](#sam-api-apiauth-adddefaultauthorizertocorspreflight): Boolean
[ApiKeyRequired](#sam-api-apiauth-apikeyrequired): Boolean
[Authorizers](#sam-api-apiauth-authorizers): CognitoAuthorizer | LambdaTokenAuthorizer | LambdaRequestAuthorizer | AWS_IAM
[DefaultAuthorizer](#sam-api-apiauth-defaultauthorizer): String
[InvokeRole](#sam-api-apiauth-invokerole): String
[ResourcePolicy](#sam-api-apiauth-resourcepolicy): ResourcePolicyStatement
[UsagePlan](#sam-api-apiauth-usageplan): ApiUsagePlan
```
**注意**
`Authorizers` 屬性包含 `AWS_IAM`，但 不需要額外的組態`AWS_IAM`。如需範例，請參閱 [AWS IAM](#sam-property-api-apiauth--examples--aws_iam)。
## Properties
`AddApiKeyRequiredToCorsPreflight`
如果已設定 `ApiKeyRequired`和 `Cors` 屬性，則設定`AddApiKeyRequiredToCorsPreflight`會導致 API 金鑰新增至 `Options` 屬性。
*類型*：布林值
*必要*：否
*預設*：`True`
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。
`AddDefaultAuthorizerToCorsPreflight`
如果已設定 `DefaultAuthorizer`和 `Cors` 屬性，則設定`AddDefaultAuthorizerToCorsPreflight`會導致預設授權方新增至 OpenAPI 區段中的 `Options` 屬性。
*類型*：布林值
*必要*：否
*預設*：True
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。
`ApiKeyRequired`
如果設定為 true，則所有 API 事件都需要 API 金鑰。如需 API 金鑰的詳細資訊，請參閱[《 API Gateway 開發人員指南》中的使用 API 金鑰建立和使用用量計劃](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。 **
*類型*：布林值
*必要*：否
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。
`Authorizers`
用於控制 API Gateway API 存取的授權方。
如需詳細資訊，請參閱[使用 AWS SAM 範本控制 API 存取](serverless-controlling-access-to-apis.md)。
*類型*：[CognitoAuthorizer](sam-property-api-cognitoauthorizer.md) \$1 [LambdaTokenAuthorizer](sam-property-api-lambdatokenauthorizer.md) \$1 [LambdaRequestAuthorizer](sam-property-api-lambdarequestauthorizer.md) \$1 AWS\$1IAM
*必要*：否
*預設*：無
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。
*其他備註*：SAM 會將授權方新增至 Api 的 OpenApi 定義。
`DefaultAuthorizer`
指定 API Gateway API 的預設授權方，該 API Gateway API 預設將用於授權 API 呼叫。
如果與此 API 相關聯之函數的 Api EventSource 設定為使用 IAM 許可，則此屬性必須設定為 `AWS_IAM`，否則會產生錯誤。
*類型：*字串
*必要*：否
*預設*：無
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。
`InvokeRole`
將所有資源和方法的整合登入資料設定為此值。
`CALLER_CREDENTIALS` 會映射到 `arn:aws:iam:::/`，使用呼叫者登入資料來叫用端點。
*有效值*：`CALLER_CREDENTIALS`、`NONE`、 `IAMRoleArn`
*類型：*字串
*必要*：否
*預設*：`CALLER_CREDENTIALS`
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。
`ResourcePolicy`
設定 API 上所有方法和路徑的資源政策。
*類型*：[ResourcePolicyStatement](sam-property-api-resourcepolicystatement.md)
*必要*：否
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。
*其他備註*：您也可以`AWS::Serverless::Function`使用 在個別 上定義此設定[ApiFunctionAuth](sam-property-function-apifunctionauth.md)。對於具有 APIs，這是必要的`EndpointConfiguration: PRIVATE`。
`UsagePlan`
設定與此 API 相關聯的用量計劃。如需用量計劃的詳細資訊，請參閱《 [API Gateway 開發人員指南》中的使用 API 金鑰建立和使用用量計劃](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。 **
此 AWS SAM 屬性會在設定此屬性時產生三個額外的 CloudFormation 資源：[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html)、 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html)和 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html)。如需此案例的資訊，請參閱 [已指定 UsagePlan 屬性](sam-specification-generated-resources-api.md#sam-specification-generated-resources-api-usage-plan)。如需所產生 CloudFormation 資源的一般資訊，請參閱 [為 產生 CloudFormation 資源 AWS SAM](sam-specification-generated-resources.md)。
*類型*：[ApiUsagePlan](sam-property-api-apiusageplan.md)
*必要*：否
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。
## 範例
### CognitoAuth
Cognito 驗證範例
#### YAML
```
Auth:
Authorizers:
MyCognitoAuth:
UserPoolArn:
Fn::GetAtt:
- MyUserPool
- Arn
AuthType: "COGNITO_USER_POOLS"
DefaultAuthorizer: MyCognitoAuth
InvokeRole: CALLER_CREDENTIALS
AddDefaultAuthorizerToCorsPreflight: false
ApiKeyRequired: false
ResourcePolicy:
CustomStatements: [{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "execute-api:/Prod/GET/pets",
"Condition": {
"IpAddress": {
"aws:SourceIp": "1.2.3.4"
}
}
}]
IpRangeDenylist:
- "10.20.30.40"
```
### AWS IAM
AWS IAM 範例
#### YAML
```
Auth:
Authorizers: AWS_IAM
```