VerifyAPIKey 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

验证 API 密钥政策允许您在运行时对 API 密钥强制执行验证，仅允许拥有已批准 API 密钥的应用访问您的 API。此政策可确保 API 密钥有效、未被撤消，并且已获批准使用与 API 产品关联的特定资源。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

如需查看展示如何构建使用验证 API 密钥政策的 API 代理的教程，请参阅通过要求 API 密钥来保护 API。

示例

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

verifyapikey.{policy_name}

关于验证 API 密钥政策

当开发者在 Apigee 上注册应用时，Apigee 会自动生成使用方密钥和密钥令牌对。您可以在 Apigee 界面中查看应用的使用方密钥和密钥令牌对，也可以通过 Apigee API 访问它们。

在应用注册时，开发者会选择一个或多个要与应用关联的 API 产品，其中 API 产品是可通过 API 代理访问的资源集合。然后，开发者会将 API 密钥（使用方密钥）作为每个请求的一部分传递到与应用关联的 API 产品中的某个 API 中。如需了解详情，请参阅发布概览。

API 密钥可以用作身份验证令牌，也可以用于获取 OAuth 访问令牌。在 OAuth 中，API 密钥称为“客户端 ID”。这些名称可以互换使用。如需了解详情，请参阅 OAuth 首页。

执行验证 API 密钥政策时，Apigee 会自动填充一组流变量。如需了解详情，请参阅下文的流变量。

元素参考

您可以在此政策中配置以下元素和属性：

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

<VerifyAPIKey> 属性

以下示例展示了 <VerifyAPIKey> 标记的属性：

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

下表介绍了所有政策父元素通用的特性：

<DisplayName> 元素

除了用于 name 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>

<APIKey> 元素

此元素指定包含 API 密钥的流变量。通常，客户端会在查询参数、HTTP 标头或表单参数中发送 API 密钥。例如，如果在名为 x-apikey 的标头中发送密钥，则可在以下变量中找到此密钥：request.header.x-apikey

属性

下表说明 <APIKey> 元素的属性

示例

在这些示例中，密钥会传入参数和名为 x-apikey 的标头。

作为查询参数：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

作为 HTTP 标头：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

作为 HTTP 表单参数：

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

<CacheExpiryInSeconds> 元素

此元素会对缓存强制执行 TTL，从而自定义缓存访问令牌到期的时间段。 支持的范围介于 1 到 180 秒之间。您可以提供流变量和默认变量。 如果提供，则流变量值优先于指定的默认值。

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

属性

下表说明 <CacheExpiryInSeconds> 元素的属性

架构

流变量

当对有效的 API 密钥强制执行验证 API 密钥政策时，Apigee 会填充一组流变量。这些变量可用于流中稍后执行的策略或代码，通常用于根据 API 密钥的属性（如应用名称、用于授权密钥的 API 产品或 API 密钥的自定义属性）执行自定义处理。

政策可填充几种不同类型的流变量，包括：

• 常规
• 应用
• 开发者
• Google Analytics
• 获利

每种类型的流变量具有不同的前缀。所有变量均为标量，但明确指定为数组的变量除外。

常规流变量

下表列出由验证 API 密钥政策填充的常规流变量。这些变量均具有以下前缀：

verifyapikey.{policy_name}

例如：verifyapikey.{policy_name}.client_id

可用变量包括：

应用流变量

政策将填充以下包含应用相关信息的流变量。这些变量均具有以下前缀：

verifyapikey.{policy_name}.app。

例如：

verifyapikey.{policy_name}.app.name

可用变量包括：

AppGroup 流变量

政策将填充以下包含 AppGroups 相关信息的流变量。仅当 verifyapikey.{policy_name}.app.appType 为“AppGroup”时，才会填充这些 AppGroup 属性。

这些变量均具有以下前缀：

verifyapikey.{policy_name}.appgroup。

例如：

verifyapikey.{policy_name}.appgroup.name

可用变量包括：

开发者流变量

政策将填充以下包含开发者相关信息的流变量。这些变量均具有以下前缀：

verifyapikey.{policy_name}.developer

例如：

verifyapikey.{policy_name}.developer.id

可用变量包括：

分析变量

对有效的 API 密钥强制执行验证 API 密钥政策时，Analytics 中会自动填充以下变量。这些变量仅由验证 API 密钥政策和 OAuth 政策填充。

您可以将这些变量和值用作维度来构建 Analytics 报告，从而了解开发者和应用的使用模式。

• apiproduct.name
• developer.app.name
• client_id
• developer.id

创收流变量

对用户进行身份验证后，VerifyAPIKey 政策会检查所有已发布的费率方案，以根据生效和到期时间来确定哪个方案（如有）有效。如果发现有效的已发布费率方案，系统会填充以下流变量：

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

错误响应示例

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

故障规则示例

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>