-NA- - Teradata AppCenter Java SDK用户指南 - Teradata AppCenter

Teradata AppCenter Java SDK用户指南

prodname
Teradata AppCenter
vrm_release
-NA-
category
用户指南
编程参考
featnum
B035-1118-000K-CHS

Teradata AppCenter Java SDK 提供 API,用于构建与 Teradata AppCenter 结合使用的 Java 应用程序。

目录

下载 Teradata AppCenter Java SDK 软件包

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

  1. 转到 https://access.teradata.com,然后登录。
  2. DOWNLOADS(下载)下,选择 Update Your Software(更新软件)
  3. Search Downloads(搜索下载) 中,搜索 teradata-appcenter-java-sdk
  4. 下载与您的 AppCenter 版本关联的 Java SDK。

启动 Teradata AppCenter SDK 客户端

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

  1. 使用以下方法之一初始化客户端:
方法 代码示例 注意事项
try-with-resources try (AppcenterClient client = new DefaultAppcenterClient()) { // your codes that utilize the client} Teradata 推荐采用 try-with-resources 语句以确保在该语句的结尾关闭每个资源。
try-catch-finally AppcenterClient client = null; try { client = new DefaultAppcenterClient(); // your codes that utilize the client } catch (...) { }finally { client.close(); } 请务必调用 client.close() in 'finally' 块以确保正确关闭资源。
Initialize AppCenter client with AppContext** AppcenterClient client = null; try { client = new DefaultAppcenterClient(); // your codes that utilize the client } catch (...) { }finally { client.close(); } 请务必调用 client.close() in 'finally' 块以确保正确关闭资源。

AppContext 的变量

可使用下列变量构造 AppContext

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

Teradata AppCenter Java SDK 支持的公共 API

Teradata AppCenter Java SDK 支持下列公共 API:

API Teradata AppCenter 兼容版本
audit AppCenter 1.3 - 1.8
cacheResult AppCenter 1.3 - 1.8
getSystems AppCenter 1.3 - 1.8
log AppCenter 1.3 - 1.8
query AppCenter 1.3 - 1.8
sendNotification AppCenter 1.3 - 1.8
setAppContext AppCenter 1.3 - 1.8
streamResultsFromQuery AppCenter 1.4 - 1.8
visualize AppCenter 1.3 - 1.8

audit API

目的

audit API 可记录重要事件,例如用户活动。您必须先构造 AuditParams,然后才能使用 audit API。

Java 代码示例

构造 AuditParams:

AuditParams auditParams = new AuditParams() 
.auditEvent("TEST") 
.message("Test message") 
.details("this is a test message") 
.result(true) 
.build(); 
`

使用 AuditParams:

client.audit(auditParams);

cacheResult API

目的

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

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

Java 代码示例

字符串示例:

String queryResult = client.query(query); 
client.cacheResult(queryResult, "application/json");

流示例:

InputStream queryResultStream = client.streamResultsFromQuery(query); 
client.cacheResult(queryResultStream, "application/json");

getSystems API

目的

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

Java 代码示例

List<String> systemNames = client.getSystems()

log API

目的

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

Java 代码示例

信息性消息示例:

Client.log(LogLevel.INFO, message)

错误消息示例:

Client.log(LogLevel.ERROR, message)

query API

目的

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

Java 代码示例

String queryResult = client.query(query);

结果示例

在下面的示例中,输出的 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
        },
        ……
      ]
    }
  ]
}

sendNotification API

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

Java 代码示例

client.sendNotification(subject, message);

setAppContext API

目的

setAppContext API 可更改现有客户端实例的上下文。它主要与 getSystems API 结合使用,用于在客户端上下文中设置新的系统。但是,您可以使用它来设置任何其他变量。

Java 代码示例

AppContext appContext = new AppContext() 
.system(“aster-system”) 
.user("") 
.password("") 
.build(); 
client.setAppContext(appContext);

streamResultsFromQuery API

目的

streamResultsFromQuery API 会查询 Teradata Database、Teradata Vantage、Aster Database、Presto 和 Hive 系统,并以 InputStream 的形式返回结果。

Java 代码示例

InputStream queryResultStream = client.streamResultsFromQuery(query);

结果示例

在下面的示例中,输出的 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
        },
        ……
      ]
    }
  ]
}

visualize API

目的

visualize API 支持 Aster 可视化、NGX 条形图和折线图以及自定义可视化。对于自定义可视化,必须捆绑可视化资产并将捆绑的 html 与应用程序一起上载。

可视化 API 有下面的两个接口:

接口 说明 Java 代码示例
String 使用来自查询 API 的字符串数据,并返回字符串格式的可视化数据 String visualizedResult = client.visualize(data, “query1”);
InputStream 使用来自 streamResultsFromQuery API 的 InputStream,并在 InputStream 中返回可视化的数据。 InputStream queryResultStream = client.streamResultsFromQuery(query);
InputStream vizResultStream = client.visualize(queryResultStream, "query1");
client.cacheResult(vizResultStream, "application/json");

请求参数

可视化 API 需要下面的两个参数:

参数 说明
data 要可视化的数据。可以是查询 API 的 JSON 输出,也可以是来自自定义可视化的定制数据。
tag 应用程序结果配置中的可视化配置的名称,如果使用的是 Aster 自定义可视化,则为 null。

打包自定义应用程序

  1. 使用以下示例 Docker 文件为自定义应用程序构建 Docker 映像:
FROM anapsix/alpine-java:jre8 
ARG JAR_FILE
LABEL tags="query1,query2" 
ENV TESTOUTDIR /tmp 
COPY sampleApp-1.0.0.jar sampleApp-1.0.0.jar 
CMD ["java","-jar", "sampleApp-1.0.0.jar"]

每个标记值都是应用程序的一个可视化配置的名称,用于标识与该应用程序关联的一个唯一的可视化。

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

AppCenter 使用示例 Docker 文件自动向设置添加两个可视化。一个可视化的名称为 query1,另一个的名称为 query2。可为每个可视化设置选择可视化类型和格式。

例如:

运行此应用程序时,AppCenter 将生成下面的两个可视化:

Query1:Sankey 类型,NPath 格式

Query2:Bar 类型,缺省格式

许可证

Copyright (C) 2016-2019 by Teradata Corporation.