PythonScript policy

Extensible policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

The Python Script policy lets you add customized Python functionality to your API proxy flow, especially when the functionality you need is beyond what the Apigee out-of-the-box policies provide.

This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types.

Python language support is provided through Jython version 2.5.2. Third-party libraries you add must be "pure Python" (implemented only in Python). For more on adding libraries, see Resource files.

Note: This feature may not be available in all Apigee plans. To see which pricing plan includes this feature, see https://cloud.google.com/apigee/pricing/.

A Python policy contains no actual code. Instead, a Python policy references a Python resource and defines the Step in the API flow where the Python script executes. You can upload your script through the Apigee UI proxy editor, or you can include it in the /resources/py directory in API proxies that you develop locally.

WARNING:
You should limit or disable SSH access to your security resources to prevent this policy from being used to access internal files, current user info, the process list, or CPU/memory utilization.

Samples

Python policy & script

Python Script policy

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Script name="Python-1">
        <DisplayName>Python-1</DisplayName>
        <ResourceURL>py://myscript.py</ResourceURL>
</Script>

In this example, the element, ResourceURL specifies the relevant Python script resource.

Python Script

This shows what you might include in the Python script itself.

import base64

username = flow.getVariable("request.formparam.client_id")
password = flow.getVariable("request.formparam.client_secret")

base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
authorization = "Basic "+base64string

flow.setVariable("authorizationParam",authorization)

Element reference

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Script name="Python-1">
    <DisplayName>Python-1</DisplayName>
    <ResourceURL>py://myscript.py</ResourceURL>
    <IncludeURL>py://myscript_dependency.py</IncludeURL>
</Script>

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

<ResourceURL> element

This element specifies the main Python file that will execute in the API flow. You can store this file at the API proxy scope (under /apiproxy/resources/py in the API proxy bundle or in the Scripts section of the API proxy editor's Navigator pane), or at the organization or environment scopes for reuse across multiple API proxies, as described in Resource files. Your code can use the objects, methods, and properties of the JavaScript object model.

<ResourceURL>py://myscript.py</ResourceURL>

Default:	None
Presence:	Required
Type:	String

<IncludeURL> element

Specifies a Python file to be loaded as dependency to the main Python file specified with the <ResourceURL> element. The scripts will be evaluated in the order in which they are listed in the policy.

Include more than one Python dependency resource with additional <IncludeURL> elements.

Warning: If your Python files are stored at the proxy or environment level, be sure they were uploaded correctly with cURL using the -F option or as a file attachment through a REST client. Content-Type is multipart/form-data. For more information, see Resource files.

<IncludeURL>py://myscript_dependency.py</IncludeURL>

Default:	None
Presence:	Optional
Type:	String

Error codes

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

运行时错误

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

提示：需要我们帮助来解决错误？点击“修复”列中的 以获取详细的问题排查信息。

故障代码	HTTP 状态	原因	修复
steps.script.ScriptEvaluationFailed	500	PythonScript 政策可能会引发几种不同的 ScriptExecutionFailed 错误。常见的错误类型包括 NameError 和 ZeroDivisionError。

部署错误

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

提示：需要我们帮助来解决错误？点击错误原因说明旁边的 即可访问问题排查页面。

错误名称	原因	修复
InvalidResourceUrlFormat	如果 PythonScript 政策的 <ResourceURL> 或 <IncludeURL> 元素中指定的资源网址格式无效，则 API 代理的部署将失败。
InvalidResourceUrlReference	如果 <ResourceURL> 或 <IncludeURL> 元素引用了不存在的 PythonScript 文件，则 API 代理的部署将失败。引用的源文件必须存在于 API 代理、环境或组织级别。

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	其中	示例
fault.name="fault_name"	fault_name 是故障名称，如上面的运行时错误表中所列。 故障名称是故障代码的最后一部分。	fault.name Matches "ScriptExecutionFailed"
pythonscript.policy_name.failed	policy_name 是抛出故障的政策的用户指定名称。	pythonscript.PythonScript-1.failed = true

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Pythonscript runtime error: "ReferenceError: "status" is not defined.\"",
    "detail": {
      "errorcode": "steps.script.ScriptExecutionFailed"
    }
  }
}

故障规则示例

<FaultRule name="PythonScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(pythonscript.PythonScript-1.failed = true) </Condition>
</FaultRule>