VerifyAPIKey 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

验证 API 密钥政策允许您在运行时对 API 密钥强制执行验证，仅允许拥有已批准 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 密钥政策

开发者在 Edge 上注册应用时，Edge 会自动生成使用方密钥并 密钥令牌对您可以在 Edge 界面中查看或访问应用的使用方密钥和密钥对 。

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

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

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

元素参考

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

<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"/>
</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>

架构

流变量

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

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

• 常规
• 应用
• 开发者
• 公司
• Google Analytics

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

常规流变量

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

verifyapikey.{policy_name}

例如：verifyapikey.{policy_name}.client_id

可用变量包括：

应用流变量

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

verifyapikey.{policy_name}.app。

例如：

verifyapikey.{policy_name}.app.name

可用变量包括：

开发者流变量

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

verifyapikey.{policy_name}.developer

例如：

verifyapikey.{policy_name}.developer.id

可用变量包括：

公司流变量

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

verifyapikey.{policy_name}.company

例如：

verifyapikey.{policy_name}.company.name

可用变量包括：

分析变量

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

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

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

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error responses

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

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

Example fault rule

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

相关主题