本文介绍了如何使用阿里云视觉智能开放平台的Java SDK,具体包括SDK的安装方法以及SDK代码示例。
阿里云视觉智能开放平台各类目视觉AI能力SDK接入、接口使用或问题咨询等,请通过钉钉群(23109592)加入阿里云视觉智能开放平台咨询群联系我们。
该版本是升级版SDK只支持Java8及以上,如不满足SDK版本所需环境要求请升级Java版本。如必须使用Java8以下版本请使用旧版Java(不推荐)。
您可以根据使用不同服务,下载对应服务的SDK包。具体服务的SDK包名称如下:
AI类目 | SDK包名称 | SDK链接 | Github链接 |
生成专区 | aigen20240111 | ||
人脸人体 | facebody20191230 | ||
文字识别 | ocr20191230 | ||
商品理解 | goodstech20191230 | ||
内容审核 | imageaudit20191230 | ||
图像识别 | imagerecog20190930 | ||
图像生产 | imageenhan20190930 | ||
分割抠图 | imageseg20191230 | ||
目标检测 | objectdet20191230 | ||
视觉搜索 | imgsearch20200320 | ||
图像分析处理 | imageprocess20200320 | ||
视频理解 | videorecog20200320 | ||
视频生产 | videoenhan20200320 | ||
视频分割 | videoseg20200320 | ||
异步任务管理 | viapi20230117 | ||
自学习 | viapi_regen20211119 | ||
人脸核身服务端20200910专用版本 | facebody20200910 |
准备工作
在使用阿里云SDK前,确保您已经注册阿里云账号并生成访问密钥(AccessKey)。具体操作,请参见创建AccessKey。
已安装视觉智能API相关服务Java SDK。
查看SDK版本
pom.xml文件中version的值以SDK获取地址中的最新版本为准。您可以通过https://mvnrepository.com/artifact/com.aliyun/SDK包名称
查看不同服务SDK的版本。
例如,通过https://mvnrepository.com/artifact/com.aliyun/facebody20191230
可以查看facebody20191230
的版本。
安装方法1:使用Maven(推荐)
如果您使用Maven管理Java项目,可以通过在pom.xml文件中添加Maven依赖安装Java SDK。例如您需要人脸人体类目下的能力,您只需引入facebody20191230
。
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>facebody20191230</artifactId>
<version>${aliyun.facebody.version}</version>
</dependency>
安装方法2:在集成开发环境(IDE)中导入JAR文件
无论您使用Eclipse还是IntelliJ作为集成开发环境,都可以通过导入JAR文件的方式安装Java SDK。
Eclipse安装
将下载的
xxx.jar
及其依赖文件复制到您的项目文件夹中。在Eclipse中打开您的项目,右键单击该项目,选择Properties。
在弹出的对话框中,单击Java Build PathLibrariesAdd JARs添加下载的JAR文件。
单击Apply and Close。
IntelliJ安装
将下载的
xxx.jar
及其依赖文件复制到您的项目文件夹中。在IntelliJ中打开您的项目,右键单击
xxx.jar
,选择Add as Library。单击Apply,然后单击OK。
配置环境变量
配置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。
阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维,具体操作,请参见创建RAM用户。
请不要将AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
Linux和macOS系统配置方法
在IntelliJ IDEA中打开终端Terminal。
执行以下命令,配置环境变量。
<access_key_id>
需替换为您RAM用户的AccessKey ID,<access_key_secret>
替换为您RAM用户的AccessKey Secret。如果后续需要进行更多权限相关的配置,具体操作请参见使用RAM Policy控制访问权限。export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id> export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>
Windows系统配置方法
新建环境变量文件,添加环境变量
ALIBABA_CLOUD_ACCESS_KEY_ID
和ALIBABA_CLOUD_ACCESS_KEY_SECRET
,并写入已准备好的AccessKey ID和AccessKey Secret。然后重启Windows系统。本操作以Windows 10为例进行说明。打开文件资源管理器,在此电脑上右键单击属性。
在右侧导航栏,单击高级系统配置。
在系统属性对话框的高级页签下,单击环境变量。
在环境变量对话框中,单击新建(W)。
在弹出的新建系统变量对话框中,添加环境变量
ALIBABA_CLOUD_ACCESS_KEY_ID
和ALIBABA_CLOUD_ACCESS_KEY_SECRET
,并写入已准备好的AccessKey ID和AccessKey Secret。重启Windows系统,使配置生效。
SDK示例
本文以RecognizeBankCard为例。
文件在上海地域OSS
每个类目的访问域名与对应地域的开通详情,请参见访问域名。
package com.aliyun.sample;
// 1、这里只是以ocr下的RecognizeBankCard能力为例,其他能力请引入相应类目的包和相关类。包名可参考本文档上方的SDK包名称,能力名可参考对应API文档中的Action参数。例如您想使用通用分割,其文档为https://help.aliyun.com/document_detail/151960.html,可以知道该能力属于分割抠图类目,能力名称为SegmentCommonImage,那么您需要将代码中ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。
import com.aliyun.ocr20191230.models.RecognizeBankCardResponse;
import com.aliyun.tea.*;
public class Sample {
/**
* 使用AK&SK初始化账号Client
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
// 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
public static com.aliyun.ocr20191230.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
/*
初始化配置对象com.aliyun.teaopenapi.models.Config
Config对象存放AccessKeyId、AccessKeySecret、endpoint等配置
*/
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
.setAccessKeyId(accessKeyId)
.setAccessKeySecret(accessKeySecret);
// 2、访问的域名。注意:这个地方需要求改为相应类目的域名,参考:https://help.aliyun.com/document_detail/143103.html
config.endpoint = "ocr.cn-shanghai.aliyuncs.com";
// 3、这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
return new com.aliyun.ocr20191230.Client(config);
}
public static void main(String[] args) throws Exception {
// 4、"YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET" 的生成请参考https://help.aliyun.com/document_detail/175144.html
// 如果您用的是RAM用户(子账号)AccessKey,还需要为RAM用户(子账号)授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html
// 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
// 创建AccessKey ID和AccessKey Secret,请参考https://help.aliyun.com/document_detail/175144.html。
// 如果您使用的是RAM用户的AccessKey,还需要为RAM用户授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html。
// 从环境变量读取配置的AccessKey ID和AccessKey Secret。运行代码示例前必须先配置环境变量。
com.aliyun.ocr20191230.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// 5、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,具体入参设置需要参考具体能力的文档
com.aliyun.ocr20191230.models.RecognizeBankCardRequest recognizeBankCardRequest = new com.aliyun.ocr20191230.models.RecognizeBankCardRequest()
.setImageURL("http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg");
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
try {
// 6、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,注意,recognizeBankCardWithOptions方法名也需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的,如能力名称为SegmentCommonImage,对应方法名应该为segmentCommonImageWithOptions。
RecognizeBankCardResponse resp = client.recognizeBankCardWithOptions(recognizeBankCardRequest, runtime);
// 获取整体结果。部分能力会输出url链接,通过toJSONString转换后可能有编码问题,但是通过单个字段获取是没问题的。
System.out.println(com.aliyun.teautil.Common.toJSONString(TeaModel.buildMap(resp)));
// 获取单个字段,这里只是一个例子,具体能力下的字段需要看具体能力的文档
System.out.println(resp.getBody().getData().getCardNumber());
} catch (com.aliyun.tea.TeaException teaException) {
// 获取整体报错信息
System.out.println(com.aliyun.teautil.Common.toJSONString(teaException));
// 获取单个字段
System.out.println(teaException.getCode());
}
}
}
需要修改的地方均在上述代码注释中标明,总结如下:
引入包的时候,需要引入相应类目的包和相关类。包名可参考上文SDK包名称,能力名称可参考对应API文档中的Action参数。
例如,您想使用通用分割能力,通过通用分割API文档可知该能力属于分割抠图类目(imageseg20191230),能力名称为SegmentCommonImage,您需要将代码中的ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。
访问的域名一定要修改为相应类目的域名,如果域名类目不匹配会报错
InvalidAction.NotFound
。关于域名详情,请参见访问域名。Client类需要使用相应类目的包下的Client类。
Request和Response需要使用相应类目的包和类。
调用Client的方法时,方法名需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的。例如,能力名称为SegmentCommonImage,对应方法名应为segmentCommonImageWithOptions。
文件在本地或可访问的URL
与文件在同地域的区别在于需要使用xxxAdvanceRequest,文件是以Stream形式通过ImageURLObject参数传入。
package com.aliyun.sample;
// 1、这里只是以ocr下的RecognizeBankCard能力为例,其他能力请引入相应类目的包和相关类。包名可参考本文档上方的SDK包名称,能力名可参考对应API文档中的Action参数。例如您想使用通用分割,其文档为https://help.aliyun.com/document_detail/151960.html,可以知道该能力属于分割抠图类目,能力名称为SegmentCommonImage,那么您需要将代码中ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。
import com.aliyun.ocr20191230.models.RecognizeBankCardResponse;
import com.aliyun.tea.*;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.net.URL;
import java.net.URLConnection;
public class Sample {
/**
* 使用AK&SK初始化账号Client
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
// 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
public static com.aliyun.ocr20191230.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
/*
初始化配置对象com.aliyun.teaopenapi.models.Config
Config对象存放 AccessKeyId、AccessKeySecret、endpoint等配置
*/
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
.setAccessKeyId(accessKeyId)
.setAccessKeySecret(accessKeySecret);
// 2、访问的域名。注意:这个地方需要求改为相应类目的域名,参考:https://help.aliyun.com/document_detail/143103.html
config.endpoint = "ocr.cn-shanghai.aliyuncs.com";
// 3、这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
return new com.aliyun.ocr20191230.Client(config);
}
public static void main(String[] args) throws Exception {
// 4、"YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET" 的生成请参考https://help.aliyun.com/document_detail/175144.html
// 如果您是用的子账号AccessKey,还需要为子账号授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html
// 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
// 创建AccessKey ID和AccessKey Secret,请参考https://help.aliyun.com/document_detail/175144.html。
// 如果您使用的是RAM用户的AccessKey,还需要为RAM用户授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html。
// 从环境变量读取配置的AccessKey ID和AccessKey Secret。运行代码示例前必须先配置环境变量。
com.aliyun.ocr20191230.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// 场景一,使用本地文件
// InputStream inputStream = new FileInputStream(new File("/tmp/bankCard.png"));
// 场景二,使用任意可访问的url
URL url = new URL("https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg");
InputStream inputStream = url.openConnection().getInputStream();
// 5、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,具体入参设置需要参考具体能力的文档
com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest recognizeBankCardAdvanceRequest = new com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest()
.setImageURLObject(inputStream);
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
try {
// 6、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,注意,recognizeBankCardAdvance方法名也需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的,如能力名称为SegmentCommonImage,对应方法名应该为segmentCommonImageAdvance。
RecognizeBankCardResponse resp = client.recognizeBankCardAdvance(recognizeBankCardAdvanceRequest, runtime);
// 获取整体结果。部分能力会输出url链接,通过toJSONString转换后可能有编码问题,但是通过单个字段获取是没问题的。
System.out.println(com.aliyun.teautil.Common.toJSONString(TeaModel.buildMap(resp)));
// 获取单个字段,这里只是一个例子,具体能力下的字段需要看具体能力的文档
System.out.println(resp.getBody().getData().getCardNumber());
} catch (com.aliyun.tea.TeaException teaException) {
// 获取整体报错信息
System.out.println(com.aliyun.teautil.Common.toJSONString(teaException));
// 获取单个字段
System.out.println(teaException.getCode());
}
}
}
需要修改的地方均在上述代码注释中标明,总结如下:
引入包的时候,需要引入相应类目的包和相关类。包名可参考上文SDK包名称,能力名称可参考对应API文档中的Action参数。
例如,您想使用通用分割能力,通过通用分割API文档可知该能力属于分割抠图类目(imageseg20191230),能力名称为SegmentCommonImage,您需要将代码中的ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。
访问的域名一定要修改为相应类目的域名,如果域名类目不匹配会报错
InvalidAction.NotFound
。关于域名详情,请参见访问域名。Client类需要使用相应类目的包下面的Client类。
Request和Response需要使用相应类目的包和类。
调用Client的方法时,方法名需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的。例如,能力名称为SegmentCommonImage,对应方法名应该为segmentCommonImageAdvance。
常见问题
调用报错如何解决?
如果您的调用出现报错,请先尝试升级SDK包到最新版本,最新版本请参考各类目SDK链接。如果您的程序中同时引入了多个类目的包,可以先尝试将这些包都升级到最新版本,避免版本之间的包冲突问题。也有可能是引入的包和您已经在使用的包发生冲突,可先通过Maven依赖分析工具解决包冲突问题。
OpenAPI界面显示的最新包在Maven仓库中找不到如何解决?
如果您发现OpenAPI界面显示的最新版本的包,在Maven仓库中找不到,这是因为新版本的包刚刚发布,仓库同步可能会有延迟,如果遇到版本不存在的情况,请稍后再试或使用Maven仓库中的最新版本。
该SDK是否可以用于Android开发?
可以。Android端调用请参考Android端直接调用。
Java升级版SDK默认不忽略证书,HTTPS请求下缺少证书会报错应如何解决?
报错信息
解决方案
升级版SDK中可以通过在Client中设置OpenAPI的请求协议,Client设置的优先级高于默认设置。更多关于忽略证书的信息,请参见HTTPS 请求配置。
文件在本地或可访问的URL场景下,使用xxxAdvanceRequest类引入SDK报错,应如何解决?
报错信息
Exception in thread "main" java.lang.NoSuchMethodError: com.aliyun.credentials.Client.getCredential()Lcom/aliyun/credentials/models/CredentialModel;
at com.aliyun.teaopenapi.Client.doRequest(Client.java:814)
at com.aliyun.teaopenapi.Client.callApi(Client.java:1083)
at com.aliyun.openplatform20191219.Client.authorizeFileUploadWithOptions(Client.java:46)
at com.aliyun.facebody20191230.Client.compareFaceAdvance(Client.java:894)
at com.test.CompareFace.main(CompareFace.java:56)
解决方案
该报错是由于出现依赖冲突导致,您需要将credentials包更新到最新版即可,依赖如下最新SDK。
<!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>credentials-java</artifactId>
<version>0.3.0</version>
</dependency>
技术支持
如果以上方法未能解决您的问题,请通过搜索钉钉群号(23109592)加入阿里云视觉智能开放平台咨询群联系我们,届时会有专业的技术人员与您对接解决问题。