PythonScript 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

您可以使用 Python 指令碼政策，在 API Proxy 流程中加入自訂的 Python 功能，特別是在需要的功能超出 Apigee 立即可用政策提供的功能時。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

Python 語言支援功能是透過 Jython 2.5.2 版提供。您新增的第三方程式庫必須是「純 Python」(僅在 Python 中實作)。如要進一步瞭解如何新增程式庫，請參閱「資源檔案」。

Python 政策不含實際程式碼。相反地，Python 政策會參照 Python 資源，並在 API 流程中定義 Python 指令碼執行的步驟。您可以透過 Apigee UI 代理程式編輯器上傳指令碼，也可以將指令碼納入在本機開發的 API 代理程式中 /resources/py 目錄中。

範例

Python 政策和指令碼

Python 指令碼政策

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

在這個範例中，ResourceURL 元素會指定相關的 Python 指令碼資源。

Python 指令碼

這會顯示您可能會在 Python 指令碼中加入的內容。

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)

元素參照

<?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>

下表說明所有政策父項元素的共同屬性：

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<ResourceURL> 元素

這個元素會指定在 API 流程中執行的主要 Python 檔案。您可以將此檔案儲存在 API proxy 範圍 (API proxy 套件中的 /apiproxy/resources/py 下方，或 API proxy 編輯器的 Navigator 窗格中的「Scripts」部分)，或是組織或環境範圍中，以便在多個 API proxy 之間重複使用，如「資源檔案」一文所述。程式碼可使用 JavaScript 物件模型的物件、方法和屬性。

<ResourceURL>py://myscript.py</ResourceURL>
預設值： 無
外觀狀態： 必填
類型： 字串

<IncludeURL> 元素

指定要載入的 Python 檔案，做為使用 <ResourceURL> 元素指定的主要 Python 檔案的依附元件。系統會按照政策中列出的順序評估腳本。

使用其他 <IncludeURL> 元素加入多個 Python 依附元件資源。

<IncludeURL>py://myscript_dependency.py</IncludeURL>
預設值： 無
外觀狀態： 選用
類型： 字串

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因 修正
steps.script.ScriptEvaluationFailed 500 PythonScript 政策可能會擲回幾種不同類型的 ScriptExecutionFailed 錯誤。常見的錯誤類型包括 NameError 和 ZeroDivisionError。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因 修正
InvalidResourceUrlFormat 如果 <ResourceURL> 中指定的資源網址格式或 PythonScript 政策的 <IncludeURL> 元素無效，API Proxy 的部署作業就會失敗。
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

錯誤回應範例

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