PYCOMMAND 命令

概念信息

集成 Python 脚本

将 Analytics 表作为数据帧传递给一个外部 Python 脚本，并且使用该 Python 脚本返回的输出在 Analytics 项目中创建一个新表。

语法

PYCOMMAND <<FIELDS> field <...n>|<FIELDS> ALL> <IF test> <TO table_name> SCRIPT path_to_script <WHILE test> <FIRST range|NEXT range> <KEEPTITLE> <SEPARATOR character> <QUALIFIER character> <PASSWORD num|PROMPT_PASSWORD> <OPEN>

参数

名称 描述

FIELDS 域名称 <...n> | FIELDS ALL

可选

要包括在发送给 Python 脚本的数据帧中的源 Analytics 表中的域或表达式。

  • FIELDS field_name包含指定的一个或多个域或者表达式

    请用空格分隔文件名。域被按照您列出它们的顺序导出。

    要导出相关域，请指定完全限定域名称（表名称.域名称）。例如：Vendor.Vendor_Name

  • FIELDS ALL包含表中的所有域

    域会按照在表布局中的顺序被导出。相关域不会被导出。
IF 测试

可选

 要处理当前记录所必须满足的条件。被传递给 Python 脚本的数据帧仅包含那些满足该条件的记录。
TO 表名

可选

要将命令结果发送到的位置：

  • table_name将结果保存到 Analytics 表

    请将表名称指定为具有 .FIL 文件扩展名的带引号的字符串。例如：TO "Output.FIL"

    默认情况下，表数据文件 (.FIL) 被保存到包含 Analytics 项目的文件夹。

    请使用绝对或相对文件路径将该数据文件保存到另外的现有文件夹：

    • TO "C:\Output.FIL"
    • TO "Results\Output.FIL"

    说明

    表名称限制为不超过 64 个字母数字字符，且不包括 .FIL 扩展名。该名称可以包括下划线字符 ( _ )，但不能包括其他特殊字符或任何空格。该名称不能以数字开头。

输出表是从 Python 脚本返回的数据帧创建的。
SCRIPT 脚本路径

文件系统上的 Python 脚本的完整或相对路径。请将脚本路径放在引号中。
WHILE 测试

可选

一个条件表达式，它必须为真以便处理每个记录。该命令被一直执行到条件的计算结果为假或者到达表的末尾为止。

说明

如果您将 WHILE 与 FIRST 或 NEXT 结合使用，请在达到一个限制时立即记下处理步骤。
FIRST 范围 | NEXT 范围

可选

要处理的记录数：

  • FIRST从第一条记录开始处理，直到达到指定的记录数为止
  • NEXT从当前选定的记录开始处理，直到达到指定的记录数为止

请使用范围指定要处理的记录数。

如果您省略 FIRST 和 NEXT，则会默认处理所有记录。
KEEPTITLE

可选

将第一行数据视为域名称而非数据。如果省略，则不会向 Python 脚本发送任何域名。

如果您想要在 Python 脚本中使用列名称检索数据，则需要此选项。
SEPARATOR 字符

可选

要用作域之间的分隔符的字符。您必须将该字符指定为带引号的字符串。

默认字符是一个逗号。

说明

请避免使用出现在输入域中的任何字符。如果 SEPARATOR 字符出现在输入数据中，则结果可能受到影响。
QUALIFIER 字符

可选

要用作文本限定符以便环绕和标识域值的字符。您必须将该字符指定为带引号的字符串。

默认字符是一个双引号。

说明

请避免使用出现在输入域中的任何字符。如果 QUALIFIER 字符出现在输入数据中，则结果可能受到影响。

PASSWORD 数字 | PROMPT_PASSWORD

可选

PASSWORD num

要使用的密码定义。

您不使用 PASSWORD 数字 提示用户提供或者指定实际密码。密码定义是指先前使用 PASSWORD 命令、SET PASSWORD 命令或 PASSWORD 分析标记提供或设置的密码。

数字是密码定义的编号。例如，如果之前已在脚本中或在调度分析脚本时提供或设置了两个密码，则 PASSWORD 2 指定使用密码 #2。

有关提供或设置密码的详细信息，请参阅：

PROMPT_PASSWORD

作为使用密码定义的替代方案，PROMPT_PASSWORD 会在 PYCOMMAND 运行时显示密码提示。

有关更多信息，请参阅 PYCOMMAND 如何使密码对 Python 脚本可用。

OPEN

可选

在命令执行后打开该命令创建的表。仅当该命令创建输出表时有效。

示例

Analytics 和 Python 脚本之间的往返数据

您将应付账款数据从 Analytics 发送到 Python 脚本，在 Python 中对数据执行一些分析或操作，然后将 Python 结果导出回到 Analytics。

Analytics 命令

PYCOMMAND 将指定的应付账款域导出到 Python 脚本 testInOutput.py，并等待脚本执行，然后将 Python 脚本的结果保存到名为 AN_Python_countrip 的新 Analytics 表中。

OPEN Ap_Trans
PYCOMMAND FIELDS Vendor_No Invoice_No Invoice_Date Invoice_Amount Prodno Quantity Unit_Cost SCRIPT "testInOutput.py" KEEPTITLE TO AN_Python_roundtrip.fil

此版本的命令会将 Ap_Trans 表中的所有域导出到 Python 脚本中。

OPEN Ap_Trans
PYCOMMAND FIELDS ALL SCRIPT "testInOutput.py" KEEPTITLE TO AN_Python_roundtrip.fil

Python 脚本 (testInOutput.py)

import sys
import os
import logging
import pandas as pd
from acl_py_util import acl_py_util
from acl_py_util import logger

def main(args):
    error_file = os.getenv("ACL_PY_ERROR_FILE")
    if not error_file:
        error_file = os.getenv('LOCALAPPDATA') + "/acl_py_utl.error"

    # 将数据从 Analytics 导入至 Python
    # 使用 Analytics 附带的 Python 函数
    df = acl_py_util.from_an()

    ''' Sample user code '''

    # 使用数据帧中的列名称和行创建 acl_py_util 日志条目
    logger.info(df)

    # 将原始数据帧复制到新数据帧
    user_df = df.copy()

    # 将 Invoice_Amount 列乘以 2
    user_df.Invoice_Amount = user_df.Invoice_Amount * 2

    # 使用数据帧中的列名称和行创建 acl_py_util 日志条目
    logger.info(user_df)

    ''' End sample user code '''

    # 将数据从 Python 导出到 Analytics
    # 使用 Analytics 附带的 Python 函数
    acl_py_util.to_an(user_df)

    # 创建 acl_py_util 日志条目记录脚本完成，并添加一个空行
    logger.info(f"*** Python script completed successfully ***\n")

if __name__ == "__main__":
    main(sys.argv)

使用 Python 脚本将数据导入 Analytics

您使用 Python 脚本将应付账款数据导入到 Analytics。

为了作为示例，Python 脚本生成了一些示例数据。通常，脚本会将数据从外部源导入到 Python，在 Python 中执行分析或进行文件准备，然后将结果导出到 Analytics。

Analytics 命令

PYCOMMAND 调用 Python 脚本 testOutput.py，然后将 Python 脚本的结果保存到名为 Input_from_Python 的新 Analytics 表中。

PYCOMMAND SCRIPT "testOutput.py" TO Input_from_Python.fil

Python 脚本 (testOutput.py)

import sys
import os
import logging
import pandas as pd
from acl_py_util import acl_py_util
from acl_py_util import logger 

def main(args):

    # 初始化应付账款数据样本
    data = {'Vendor_Number': ['12701', '10134', '11663'],
            'Vendor_Name': ['Harris Projects', 'Stars Trading', 'More Power Industries'],
            'Vendor_City': ['Baton Rouge', 'Milwaukee', 'Los Angeles'],
            'Invoice_Number': ['232556', '74841', '5986811'],
            'Invoice_Date': ['2024-10-22', '2024-10-22', '2024-10-23'],
            'Invoice_Amount': [2064.48, 18883.34, 1145.58],
            'Product_Number': ['030302903', '030302303', '090501551'],  
            'Quantity': [204, 458, 626],
            'Unit_Cost': [10, 41, 1]}

    # 创建数据帧
    df = pd.DataFrame(data)

    # 使用数据帧中的列名称和行创建 acl_py_util 日志条目
    logger.info(df)

    # Sample user code

    user_df = df

    # 用户代码的最终示例

    # 将数据从 Python 导出到 Analytics
    # 使用 Analytics 附带的 Python 函数
    acl_py_util.to_an(user_df)

    # 创建 acl_py_util 日志条目记录脚本完成，并添加一个空行
    logger.info(f"*** Python script completed ***\n")

if __name__ == "__main__":
    main(sys.argv)

备注

PYCOMMAND 的工作原理

PYCOMMAND 将 Analytics 表作为数据帧传递给外部 Python 脚本，在 Python 脚本执行期间等待，然后使用 Python 脚本返回的输出在 Analytics 中创建一个新表。在运行 Analytics 脚本的过程中，您可以根据需要多次使用 PYCOMMAND。

Analytics 安装中包含两个 Python 函数，您可以在 Python 脚本中使用它们来输入和输出数据：

  • 输入数据acl_py_util.from_an() 将数据从 Analytics 导入 Python

  • 输出数据acl_py_util.to_an() 将数据从 Python 导出至 Analytics

日志文件

Analytics 创建了两个与 PYCOMMAND 关联的日志文件。日志可以帮助您排除 Analytics 和 Python 之间的集成故障，以及调试关联 Analytics 和 Python 脚本中的错误。

日志文件存储在 Analytics 项目文件夹中：

  • aclpython.log – 当 PYCOMMAND 失败时记录 Analytics 错误消息

  • acl_py_util.log – 记录 Python 脚本输出的消息

Set up acl_py_util.log

acl_py_util.log 是 Analytics 安装中附带的可配置日志。按照以下步骤设置和配置日志。

说明

您必须为要使用它的每个 Python 脚本单独设置和配置日志。

  1. 在 Python 脚本顶部的 import 语句块中，添加以下语句：

    from acl_py_util import logger

  2. 在 Python 脚本中任何要创建日志条目的位置，添加以下行：

    logger.info(Python_object)

    例如：

    • logger.info(dataframe_name.head(10)) 会创建一个具有列名称的日志条目，并且前 10 行都来自指定数据帧的当前状态。

    • logger.info(f"*** Python script completed ***\n") 插入到脚本末尾，会在日志中记录脚本完成情况，并为运行的单独脚本在日志详细信息之间插入一个空行。

PYCOMMAND 如何使密码对 Python 脚本可用

当 PYCOMMAND 包含 PASSWORD 或 PROMPT_PASSWORD 参数时，Python 脚本可以使用用户提供的密码。该密码将暂时且安全地存储在内存中的 ACL_PY_PASSWORD 环境变量内。该密码不会出现在 Analytics 日志中。

要访问 Python 脚本中的 password 环境变量，请使用以下语法定义 Python 变量：

password_from_analytics = os.getenv("ACL_PY_PASSWORD")