API Connect 上下文变量

在组合件操作中定义缺省参数值时或在定义策略时使用 getContext() 函数时可引用的 IBM® API Connect 上下文变量的列表。

提供了以下各表：

常规上下文变量。
OAuth 上下文变量 - DataPower Gateway ( v5 兼容)。
应用程序证书上下文变量。
API 活动日志记录上下文变量。
GraphQL 上下文变量。

有关实现程序集组件的更多信息，请参阅在 OpenAPI 2.0 API 程序集中包含元素，在 OpenAPI 2.0 API 程序集中包含元素，有关如何在 API Connect 中引用上下文变量的信息，请参阅 API Connect 中的变量引用，以及在 GatewayScript 和 DataPower API Gateway 中使用上下文变量和 XSLT 策略。

有关创建用户定义策略的更多信息，请参阅编写策略。

常规上下文变量

注：

对于计划变量（例如，plan.name 或 plan.version），仅当请求的操作需要标识且客户机通过认证检查时，计划信息才可用。
如果将 API 部署到 DataPower® Gateway (v5 compatible) ，那么不支持将表单输入作为参数传递到 API ，但客户机标识和客户机密钥除外。如果将 API 部署到 DataPower API Gateway，那么此限制不适用。

表 1. API Connect 上下文变量
名称	描述	许可权
`api.catalog.id`	用于在其中发布 API 的目录的标识。	读/写
`api.catalog.name`	用于在其中发布 API 的目录的名称。	读/写
`api.catalog.path`	表示此目录的路径段。	读/写
`api.endpoint.address`	API Gateway 端点的地址。	读/写
`api.endpoint.hostname`	API Gateway 端点的主机名（按应用程序的请求）。	读/写
`api.id`	API 的标识。	读/写
`api.name`	API 的名称; 这对应于 API 的 OpenAPI 定义中的 `x-ibm-name` 字段。	读/写
`api.operation.id`	操作标识。	读/写
`api.operation.path`	操作的路径。	读/写
`api.org.id`	API 提供者的组织标识。	读/写
`api.org.name`	API 提供者的组织短名称。	读/写
`api.properties.propertyname`	定制 API 属性的名称。属性值特定于目录。注：仅有权从用户界面（而不能从 GatewayScript）对定制属性执行写入操作。	读/写
`api.root`	API 基本路径。	读/写
`api.type`	API 类型：REST 或 SOAP。	读/写
`api.version`	API 的版本字符串。	读/写
`client.app.id`	请求上接收到的客户机标识或应用程序键。	读/写
`client.app.'lifecycle-state'`	调用客户机应用程序的生命周期状态。可能的值如下所示： `DEVELOPMENT` `PRODUCTION` （缺省值）	读/写
`client.app.metadata.key`	应用程序元数据键的字符串值，其中，`key` 是键的名称。您可以通过使用 apic apps:create 或 apic apps:update 命令向应用程序添加元数据键；在传递到命令的配置文件参数中包含元数据键。例如： `apic apps:create myapp.yaml --server myserver.com --org myorg --catalog mycatalog --consumer-org mycorg` 其中，myapp.yaml 包含以下内容： `name: myapp title: My test application metadata: key1: value1 key2: value2 key3: value3 key4: value4 key5: value5` 然后，您可以使用上下文变量在 API 组合件策略中检索元数据键的值，例如以下内容： `client.app.metadata.key3` 请注意，添加应用程序元数据可能会影响网关事务性能。	读/写
`client.app.name`	所识别的发出请求的应用程序的名称。	读/写
`client.app.secret`	请求中接收到的客户机密钥。	读/写
`client.app.type`	发出请求的客户机应用程序的类型。	读/写
`client.org.id`	拥有此应用程序的组织的唯一标识键。	读/写
`client.org.name`	拥有此应用程序的组织的名称。	读/写
`client.result`	客户机安全策略的结果，即 `SUCCESS` 或 `FAILURE`。	读/写
`client.third_party.type`	用于对抽取的客户机凭证进行第三方认证的用户注册表类型。可能的值为 `LDAP` 和 `auth-url`。	读/写
`client.third_party.headers`	添加到在第三方认证期间发送到此 API 认证 URL 的请求的头的数组。	读/写
`client.third_party.response.authenticated`	第三方认证结果。可能的值如下所示： `true`：认证成功。 `false`：认证失败。	读/写
`client.third_party.response.user`	用于第三方认证的用户。	读/写
`client.title`	请求中收到的凭证的标题。	读/写
`env.name`	用于在其中发布 API 的目录的名称。	读/写
`env.path`	表示此目录的路径段。	读/写
`error.message`	错误的消息文本。	读/写
`error.name`	错误的名称。	只读
`log`	组合件记录操作中收集的事务数据。	读/写
`message.attachments`	多重部件消息中的附件数组。	读/写
`message.attachments[].body`	多部分消息中的附件有效内容。	读/写
`message.attachments[].headers`	多部分消息中的附件头。	读/写
`message.body`	请求或响应信息的有效载荷。注: `getContext()` 函数不支持 `message.body` 上下文变量。改为使用 `getvariable()` 函数。	读/写
`message.headers.name`	消息的当前指定头的值或多部分消息的根部分的当前指定头的值。 `name` 段不区分大小写。	读/写
`message.original.headers.name`	HTTP 消息的原始指定头的值。组合件包含调用操作时，会自动使用所调用 URL 的响应消息的原始指定头来填充值。 `name` 段不区分大小写。	只读
`message.package.headers.name`	多部分消息的当前指定头的值。 `name` 段不区分大小写。	读/写
`message.status.code`	响应的 HTTP 状态码。	读/写
`message.status.reason`	响应的 HTTP 原因短语。	读/写
`message.variables.name`	消息中属性的值。例如，当 `myvar` 是消息中的属性时，可以通过阅读 `message.variables.myvar` 来检索 `myvar` 属性的值。	读/写
`plan.name`	计划的名称。	读/写
`plan.id`	计划的唯一标识。	读/写
`plan.rate-limit`	计划的速率限制，即每个时间间隔内的 API 调用数。	读/写
`plan.rate-limit[index].hard-limit`	由 `[index]` 标识的速率限制方案的硬限制设置。	读/写
`plan.rate-limit[index].value`	由 `[index]` 标识的比率限制方案的值。语法为 `rate/interval`。	读/写
`plan.spaceId`	计划包含在其中的空间的唯一标识。	读/写
`plan.spaceName`	计划包含在其中的空间的名称。	读/写
`plan.version`	计划的版本号。	读/写
`request.authorization`	解析的 HTTP `authorization` 头。	只读
`request.body`	入局请求的有效内容。	只读
`request.content-type`	标准的 Content-Type 值。	只读
`request.date`	表示网关收到请求的大致时间的日期对象。	只读
`request.headers.name`	HTTP 请求的原始指定头的值，或多部分请求的根部分的当前指定头的值。 `name` 段不区分大小写。只能在预流策略中修改请求头。有关更多信息，请参阅自定义预流策略。	读/写
`request.original.headers.name`	原始指定的 HTTP 请求头的值。仅当修改请求头时才会创建此变量。 `name` 段不区分大小写。	只读
`request.package.headers.name`	多部分请求的指定头的值。 `name` 段不区分大小写。	只读
`request.parameters`	您可以从路径和查询参数获取传入参数。
`request.parameters.name.locations`	字符串数组，用于指定与名称中指定的参数相关联的参数类型。受支持的参数类型关键字如下所示。 `formData` 参数作为表单数据位于主体中 `header` 参数位于请求头中 `path` 参数位于路径中 `query` 参数位于查询中	只读
`request.parameters.name.values`	包含与名称中指定的参数相关联的参数类型值的数组。例如，当第一个值是 `request.parameters.myparam.locations[]`中的 `path` 时， `request.parameters.myparam.values[]` 中的第一个值是与 `myparam`关联的路径值的数组。只能在预流策略中修改请求参数。有关更多信息，请参阅自定义预流策略。	读/写
`request.original.parameters.name.values`	包含与 `name` 中指定的参数相关联的参数类型的原始值的数组。仅当修改请求参数值时才会创建此变量。	只读
`request.path`	`request.uri` 的路径段，以 API 的基本路径开头，包含基本路径开头所使用的“/”字符。	只读
`request.protocol`	接收请求时使用的协议：`http` 或 `https`。	只读
`request.querystring`	请求查询字符串，无前置问号。	只读
`request.search`	请求查询字符串，含前置问号。	只读
`request.uri`	来自应用程序的完整 HTTP 请求 URI。	只读
`request.verb`	此请求的 HTTP 动词。	只读
`session.apiGateway`	接收请求的网关。	只读
`session.apiGatewayName`	API Manager 中定义的 API 网关的名称。	只读
`session.clientAddress`	发送请求的客户机的地址。	只读
`session.domainName`	网关所属的域的名称。	只读
`session.globalTransactionID`	日志中的全局事务标识。	只读
`session.localAddress`	DataPower® Gateway 上网关的地址。	只读
`session.timeStarted`	网关开始处理请求的时间。	只读
`session.transactionID`	网关请求的事务标识。	只读
`system.datetime`	返回一个字符串，表示网关的系统时区内的当前日期和时间。	只读
`system.time`	返回一个字符串，表示网关的系统时区内的当前时间。	只读
`system.time.hour`	返回 0 到 23（含）之间的数字，表示网关的系统时区内的当前时间的小时值。	只读
`system.time.minute`	返回 0 到 59（含）之间的数字，表示网关的系统时区内的当前时间的分钟值。	只读
`system.time.seconds`	返回 0 到 59（含）之间的数字，表示网关的系统时区内的当前时间的秒值。	只读
`system.date`	返回一个字符串，表示网关的系统时区内的当前日期。	只读
`system.date.day-of-week`	返回 1 到 7（含）之间的数字，表示网关的系统时区内本周的某一天。	只读
`system.date.day-of-month`	返回 1 到 31 之间的数字，表示网关的系统时区内本月的某一天。	只读
`system.date.month`	返回 1 到 12 之间的数字，表示网关的系统时区内的月份。	只读
`system.date.year`	返回一个四位数的数字，表示网关的系统时区内的年份。	只读
`system.timezone`	返回网关的系统时区 ISO 8601 标识，其中可能包含一个符号、小时值（两位数）和分钟值。例如，`-04:00`。	只读

OAuth 上下文变量 DataPower Gateway (v5 compatible)

本节所述 OAuth 上下文变量仅适用于 DataPower Gateway (v5 compatible)。有关适用于 DataPower API Gateway 的 OAuth 上下文变量的详细信息，请参阅 OAuth 上下文变量。

表 2. OAuth 上下文变量 (DataPower Gateway (v5 compatible))。
注意：大多数 OAuth 上下文变量只有在 IBM API Connect 作为 OAuth 资源服务器时才可用。但是，当与第三方提供程序集成时，`oauth.introspect` 变量也可用。
名称	描述
`oauth.access-token`	如果请求已通过 OAuth 认证，那么此变量包含访问令牌字符串。
`oauth.miscinfo`	此变量包含“认证 URL”和“元数据 URL”头中显式包含的信息。有关更多信息，请参阅验证 URL。
`oauth.not-after`	如果请求已通过 OAuth 认证，那么此变量包含令牌到期的日期。
`oauth.not-before`	如果请求已通过 OAuth 认证，那么此变量包含发放令牌的日期。
`oauth.resource-owner`	如果请求已通过 OAuth 认证，那么此变量包含资源所有者的名称。
`oauth.scope`	如果请求已通过 OAuth 认证，那么此变量包含此访问令牌的范围。
`oauth.introspect.active`	始终可用于自省。布尔值。
`oauth.introspect.response`	始终可用于自省。显示当前的完整响应有效内容。示例有效内容值： `{“active”:true, “client_id”, “xxx-xxx”, “token_type”, “bearer”, “scope”:“neon”}`
其他变量可能来自第三方，格式为：`oauth.introspect.<variable>`	通过解码先前示例有效内容，可以进一步处理以下变量。 `oauth.introspect.client_id: xxx-xxx oauth.introspect.token_type: bearer oauth.introspect.scope: neon`

应用程序证书上下文变量

下表列出了使用证书验证 API 访问权限时可用的上下文变量，但这些变量会因使用的签名机制而异；如欲了解更多信息，请参阅 Internet X.509 Public Key Infrastructure Certificate and CRL Profile 规范。

表 3. 应用程序证书上下文变量
名称	描述
`application.certificate.Base64`	Base64 格式。
`application.certificate.fingerprint`	指纹
`application.certificate.Version`	版本
`application.certificate.SerialNumber`	序列号
`application.certificate.SignatureAlgorithm`	签名算法
`application.certificate.Issuer`	证书发布者
`application.certificate.Subject`	主题
`application.certificate.NotBefore`	此日期前无效
`application.certificate.NotAfter`	此日期后无效
`application.certificate.SubjectPublicKeyAlgorithm`	主题公用密钥的算法
`application.certificate.SubjectPublicKeyBitLength`	主题公用密钥的长度
`application.certificate.KeyValue.type`	各种上下文变量，这些变量依赖于算法和密钥。下面是可能的上下文变量： `application.certificate.KeyValue.RSAKeyValue.Modulus` `application.certificate.KeyValue.RSAKeyValue.Exponent`

API 活动日志记录上下文变量

如果针对 API 启用了活动日志记录，那么将创建 log 上下文变量：log 上下文变量包含与 API 执行事件相关的数据。在 API 执行完成时，log 上下文变量将写入到存储的 API 事件记录，供 API 分析后续访问。有关 log 上下文变量中包含的字段的详细信息，请参阅 API 事件记录字段。

启用和配置活动日志记录的方式取决于正在使用的网关类型，如下所示：

如果使用 DataPower API Gateway ，则在 API 配置设置中配置活动记录；请参阅配置活动记录 ( OpenAPI 2.0 ) 或配置活动记录 ( OpenAPI 3.0 )。
如果使用 DataPower Gateway (v5 compatible) ，则可通过向 API 程序集添加活动日志策略来配置活动日志。

活动日志记录配置定义了 log 上下文变量的缺省内容，但您可以在 API 组合件中进行修改；例如：

使用设置变量策略添加自己的数据值。
使用 Redaction 策略删除或编辑数据值；请参阅 Redaction - DataPower API Gateway 或 Redaction - DataPower Gateway ( v5 兼容)。
使用日志策略修改或替换 log 上下文变量。

GraphQL 上下文变量

从 API 处理和组合件操作生成的 GraphQL 查询和响应变量将存储在 API 上下文的 message.attributes.graphql 上下文变量中。

表 4. GraphQL 上下文变量
名称	描述
`message.attributes.graphql`	GraphQL 消息的查询和响应属性。
`message.attributes.graphql.query`	GraphQL 查询的属性，包括查询字符串、操作名称和变量。
`message.attributes.graphql.query.query`	GraphQL 查询字符串。
`message.attributes.graphql.query.variables`	GraphQL 变量的映射。
`message.attributes.graphql.query.operationName`	要执行的操作的名称。
`message.attributes.graphql.query.operationType`	要执行的操作的类型。
`message.attributes.graphql.request`	GraphQL 请求的属性。
`message.attributes.graphql.request.fieldCost`	查询中访问的所有字段的成本的加权总和。在模式中配置每个字段访问的成本。此计数包含字段成本未设置为 0.0 的字段。
`message.attributes.graphql.request.fieldCounts`	给定查询可检索每个字段的最大次数。此数字等于负责生成字段值的解析器需要运行的次数。此计数包含字段成本未设置为 0.0 的字段。
`message.attributes.graphql.request.typeCost`	查询中检索的所有类型的成本的加权总和。在模式中配置每个类型的成本。此计数包含类型成本未设置为 0.0 的类型。
`message.attributes.graphql.request.typeCounts`	给定查询可检索每种类型的值的最大次数。此计数包含类型成本未设置为 0.0 的类型。
`message.attributes.graphql.response.fieldCost`	查询响应中所有字段的成本的加权总和。在模式中配置每个字段访问的成本。如果无法根据请求中的分析配置来计算此总和，那么字段成本表示为可分配的最大整数值。
`message.attributes.graphql.response.fieldCounts`	在查询响应中检索每个字段的次数。此数字等于负责生成字段值的解析器需要运行的次数。如果无法根据请求中的分析配置来计算此总和，那么字段计数表示为可分配的最大整数值。
`message.attributes.graphql.response.typeCost`	查询响应中所有类型的成本的加权总和。在模式中配置每个类型的成本。如果无法根据请求中的分析配置来计算此总和，那么类型成本表示为可分配的最大整数值。
`message.attributes.graphql.response.typeCounts`	每个类型的值包含在查询响应中的次数。如果无法根据请求中的分析配置来计算此总和，那么类型计数表示为可分配的最大整数值。
`message.attributes.parse.GraphQLIntrospection`	组合件 GraphQL 自省操作的自省类型。解析 GraphQL 查询时，系统将使用下列其中一个值填充此上下文变量： `not-introspection` `custom-introspection` `default-introspection`