Teradata AppCenter Python SDK用户指南

Teradata AppCenter Python SDK 提供 API，用于构建结合 Teradata AppCenter 使用的 Python 应用程序。

下载 Teradata AppCenter Python SDK 软件包

必须拥有 Teradata 用户帐户，才能访问该 Python SDK 软件包。

转到 https://access.teradata.com，然后登录。
在 DOWNLOADS（下载）下，选择 Update Your Software（更新软件）。
在 Search Downloads（搜索下载） 中，搜索 teradata-appcenter-python-sdk。
下载与您的 AppCenter 版本关联的 Python SDK。

安装 Teradata AppCenter Python SDK

如果 Python 是使用 python.org 提供的安装程序或使用 Homebrew 安装的，则您应该已经安装了 pip。

注意： 安装期间，pip 访问 Internet 以检索 Python SDK 依赖项。如果不希望 pip 访问 Internet，请先下载并安装 Python SDK 依赖项软件包再安装 Teradata AppCenter Python SDK。

使用 pip 安装 Teradata AppCenter Python SDK：

 pip install teradata-appcenter-python-sdk-<version_num>.tar.gz

可选 - 下载 Teradata AppCenter Python SDK 依赖项软件包

如果不希望 pip 访问 Internet，请先下载并安装 Python SDK 依赖项软件包，再安装 Teradata AppCenter Python SDK 软件包。

必须拥有 Teradata 用户帐户，才能访问该 Python SDK 依赖项软件包。

转到 https://access.teradata.com，然后登录。
在 Search Teradata Support（搜索 Teradata 支持） > DOWNLOADS（下载）下，选择 Update Your Software（更新软件）。
在 Search Downloads（搜索下载） 中，搜索 teradata-appcenter-python-sdk-with-deps。
下载与您的 AppCenter 版本关联的依赖项软件包。

可选 - 脱机安装 Teradata AppCenter Python SDK 依赖项软件包

如果已下载了 Teradata AppCenter Python SDK 依赖项软件包，请使用下列命令安装该软件包：

tar -xvf teradata-appcenter-python-sdk-with-deps-<version_num>.tar.gz

pip install --no-index --find-links=teradata-appcenter-python-sdk-<version_num>/.deps -r teradata-appcenter-python-sdk-<version_num>/requirements.txt

pip install teradata-appcenter-python-sdk-with-deps-<version_num>.tar.gz

启动 Teradata AppCenter SDK 客户端

必须先启动 Teradata AppCenter 客户端，然后才能使用 Teradata AppCenter Python SDK。

使用以下方法之一初始化客户端：

方法	代码示例	注意事项
import 和创建客户端	`from appcenter_sdk.client import AppContext` `from appcenter_sdk.client import DefaultAppCenterClient` `import logging` `with DefaultAppCenterClient() as client:`	所有上下文信息均通过环境变量初始化。
使用 AppContext 创建和启动客户端*	`appContext = AppContext(app_center_base_url=` `'https://appcenter.example.com',` `system='aster-system'` `with DefaultAppCenterClient(appContext) as client:`	无

AppContext 的变量

可使用下列变量构造 AppContext：

变量	说明	示例
system	数据源名称	`"****-system"`
database	数据库名称	`"appcenter-examples"`
user	用于访问数据源的用户名	`"user"`
password	用于访问数据源的密码	`"pass"`
catalog	Presto 系统的目录	`"hive"`
schema	Presto 系统的模式	`"default"`
Job_config	作业参数	`{"param1":"value", "param2":"value"}`
app_config	应用程序参数定义	`{"param1":{"type":"text","default_value":"default","required":false}}`
result_config	可视化配置	`{"query1":{"name":"query1","type":"sankey","format":"npath"}}`
app_center_base_url	AppCenter 实例基本 URL	`"https://appcenter.example.com"`

Teradata AppCenter Python SDK 支持的公共 API

Teradata AppCenter Python SDK 支持下列公共 API：

API	Teradata AppCenter 兼容版本
audit	AppCenter 1.3 - 1.8
cache_result	AppCenter 1.3 - 1.8
get_systems	AppCenter 1.3 - 1.8
log	AppCenter 1.3 - 1.8
query	AppCenter 1.3 - 1.8
query_streaming	AppCenter 1.4 - 1.8
send_notification	AppCenter 1.3 - 1.8
set_context	AppCenter 1.4 - 1.8

audit API

目的

审计 API 记录重要事件，如用户活动。

Python 代码示例

client.audit(audit_event='TEST', message='Test message', result=True, details='this is a test message')

cache_result API

目的

cache_result API 缓存查询结果或可视化结果，因此您可以查看结果或与其他用户共享这些结果。cacheResult API 接受字符串或流（类文件对象或生成器）形式的结果。对于大型结果，Teradata 建议您使用流减少占用的内存。

作业结果自生成起 30 天内有效，之后将过期。root 用户可以通过 UI 中的设置将缺省值更改为介于 1 到 365 天之间的值。

Python 代码示例

缓存字符串结果：

client.cache_result(query_result, 'application/json')
client.cache_result(visualized_result, 'text/html')

缓存流结果：

client.cache_result(query_result_stream, 'application/json', stream=True)
client.cache_result(visualized_result_stream, 'text/html', stream=True)

get_systems API

目的

get_systems API 从 AppCenter 检索可用系统的名称。

Python 代码示例

available_systems = client.get_systems()

log API

目的

日志 API 用于记录与该应用程序关联的信息性消息或错误消息。消息属于 UI 中开发提供的应用程序日志的一部分。

Python 代码示例

信息性消息示例：

client.log(logging.INFO, message)

错误消息示例：

client.log(LogLevel: ERROR, INFO, message)

query API

目的

查询 API 用于查询 Teradata Database、Teradata Vantage、Aster Database、Presto 和 Hive 系统，并返回 JSON 字符串形式的结果。

Python 代码示例

查询 API 函数调用：

query_result = client.query(query='select issue as term , count ( * ) as tf_idf from consumer_complaints group by issue')

结果示例

在下面的示例中，输出的 JSON "columns" 部分中包含介绍每列的名称和类型的列元数据。"data" 部分中包含来自查询的数据。

{
  "queueDuration": 33,
  "queryDuration": 47646,
  "results": [
    {
      "resultSet": true,
      "columns": [
        {
          "name": "issue",
          "type": "varchar"
        },
        {
          "name": "issue_count",
          "type": "bigint"
        }
      ],
      "data": [
        {
          "issue": "APR or interest rate",
          "issue_count": 125
        },
        {
          "issue": "Account opening, closing, or management",
          "issue_count": 804
        },
        ……
      ]
    }
  ]
}

query_streaming API

目的

squery_streaming API 查询 Teradata Database、Teradata Vantage、Aster Database、Presto 和 Hive 系统，并返回 InputStream 形式的结果。

调用 query_streaming API 时必须使用 "with" 块。如果尝试直接调用，将出错。

Python 代码示例

查询 API 函数调用：

with client.query_streaming(query) as iter:
     for data in iter:
         if data:
             decoded_line = data.decode('utf-8')
             client.log(logging.INFO, decoded_line)

结果示例

在下面的示例中，输出的 JSON "columns" 部分中包含介绍每列的名称和类型的列元数据，而 "data" 部分中则包含来自查询的数据。

{
  "queueDuration": 33,
  "queryDuration": 47646,
  "results": [
    {
      "resultSet": true,
      "columns": [
        {
          "name": "issue",
          "type": "varchar"
        },
        {
          "name": "issue_count",
          "type": "bigint"
        }
      ],
      "data": [
        {
          "issue": "APR or interest rate",
          "issue_count": 125
        },
        {
          "issue": "Account opening, closing, or management",
          "issue_count": 804
        },
        ……
      ]
    }
  ]
}

send_notification API

目的

如果 root 用户已在 UI 中的设置内配置了电子邮件帐户，send_notification API 将向作业和应用程序所有者发送电子邮件通知。

Python 代码示例

client.send_notification(subject, msg)

set_context API

目的

set_context API 用于更改现有客户端实例的上下文。它通常与 get_systems API 结合使用，用于在客户端上下文中设置新的系统。

Python 代码示例

context = AppContext(system=new_system_name,
                     user=****,
                     password=****)

client.set_context(context)

打包自定义应用程序

使用以下示例 Docker 文件为自定义应用程序构建 Docker 映像：

FROM python:3.5-alpine

COPY teradata-appcenter-python-sdk-1.4.tar.gz .
COPY app.py .

RUN apk add --update python3
RUN pip3 install teradata-appcenter-python-sdk-1.4.tar.gz

CMD [ "python3", "app.py" ]

标记中的每个值是应用程序结果配置中的可视化配置的名称，并标识与结果配置关联的唯一可视化。

多个标记必须是不带尾随空格或前导空格的完整单词的逗号分隔列表。

Teradata AppCenter Python SDK用户指南 - Teradata AppCenter