如何通过本地文件或网络文件链接生成URL_视觉智能开放平台(VIAPI)-阿里云帮助中心

使用阿里云视觉智能开放平台服务时，需要传入文件URL，视觉智能平台根据传入的文件URL对文件进行智能处理。本文介绍如何处理本地文件或网络文件链接。

背景信息

阿里云视觉智能开放平台服务的接口响应时间依赖文件的下载时间，为了保证被检测文件不会下载超时，建议您使用阿里云OSS存储文件。

说明

阿里云视觉智能开放平台视觉AI能力API接入、接口使用或问题咨询等，请通过钉钉群（23109592）加入阿里云视觉智能开放平台咨询群联系我们。

场景一：上海地域OSS文件

登录OSS管理控制台。
创建存储空间。
创建Bucket选择区域时，需要选择与视觉智能开放平台对应服务能力相同的区域，当前视觉智能开放平台各服务支持的区域为华东2（上海）。
说明
如果您的OSS所在地域不是华东2（上海），请参见场景二：非上海地域OSS文件进行调用。
上传本地文件到OSS服务。
具体操作请参见上传文件。
查看文件URL。
在已上传图片列表中，单击详情查看并复制图片URL。

场景二：非上海地域OSS文件

对于非OSS文件，或者您的OSS所属地域不是华东2（上海），推荐您使用SDK进行调用。

配置环境变量

配置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。

重要

阿里云账号AccessKey拥有所有API的访问权限，建议您使用RAM用户进行API访问或日常运维，具体操作，请参见创建RAM用户。
请不要将AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。

Linux和macOS系统配置方法
1. 在IntelliJ IDEA中打开终端Terminal。
2. 执行以下命令，配置环境变量。
  <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为例进行说明。
1. 打开文件资源管理器，在此电脑上右键单击属性。
2. 在右侧导航栏，单击高级系统配置。
3. 在系统属性对话框的高级页签下，单击环境变量。
4. 在环境变量对话框中，单击新建(W)。
5. 在弹出的新建系统变量对话框中，添加环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET，并写入已准备好的AccessKey ID和AccessKey Secret。
6. 重启Windows系统，使配置生效。

方式一（推荐方式）

使用各语言对应的新版SDK，目前新版SDK已经支持文件在本地或者非上海地域OSS文件，与文件在同地域的区别在于，需要使用xxxAdvanceRequest将文件以stream形式通过ImageURLObject参数（注意：这里的参数会随语言的不同参数的Object值命名会有所不同，请参考调用能力文档看请求参数的命名。）传入进行后续调用，详情请参见各语言SDK参考。

方式二

如果您无法使用新版SDK，可使用viapiutils显式生成URL，以下为各个语言对应的操作步骤。

重要

该方式使用阿里云视觉智能开放平台官方OSS-Bucket作为临时存储，仅为方便用户方便调试接口使用，文件存储有效期为1天。该方式非官方推荐方式，不保证SLA，该方式是所有用户共享总共1万QPS。如果在高峰时段，可能会因为过多用户使用OSS存储，而导致您调用接口失败。所以请勿在生产环境使用视觉智能开放平台官方的OSS-Bucket作为存储。此上传接口不推荐付费用户使用。

例如，您购买了某个API 100QPS的使用服务，但如果仍使用免费OSS-Bucket，则仍将与其他用户共享总共1万QPS的OSS并发使用量，可能因OSS并发量受限，而无法使用到100QPS的调用量上限。

Java SDK

请安装如下Java SDK包。要求Java8及以上环境，如不满足SDK版本所需环境要求请升级Java版本。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>viapi-utils</artifactId>
    <version>1.0.2</version>
</dependency>

具体代码示例如下。

import com.aliyun.com.viapi.FileUtils;
public class Main {
    public static void main(String[] args) throws Exception {
        // 创建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。运行代码示例前必须先配置环境变量。      
        String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");     
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        // 场景一，使用本地文件
        String file = "/tmp/bankCard.png";
        // 场景二，使用任意可访问的url
        // String file = "https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg";
        FileUtils fileUtils = FileUtils.getInstance(accessKeyId, accessKeySecret);
        String ossUrl = fileUtils.upload(file);
        // 生成的url，可用于调用视觉智能开放平台的能力
        System.out.println(ossUrl);
    }
}

Python SDK

请安装如下Python SDK。最低环境要求Python3及以上环境，如不满足SDK版本所需环境要求请升级Python版本。

pip install oss2
pip install aliyun-python-sdk-viapiutils
pip install viapi-utils

具体代码示例如下。

from viapi.fileutils import FileUtils
# 创建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。运行代码示例前必须先配置环境变量。
file_utils = FileUtils(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'])
# 场景一，使用本地文件，第一个参数为文件路径，第二个参数为生成的url后缀，但是并不能通过这种方式改变真实的文件类型，第三个参数True表示本地文件模式
# oss_url = file_utils.get_oss_url("/tmp/bankCard.png", "png", True)
# 场景二，使用任意可访问的url，第一个url，第二个参数为生成的url后缀，但是并不能通过这种方式改变真实的文件类型，第三个参数False表示非本地文件模式
oss_url = file_utils.get_oss_url("https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg", "jpg", False)
# 生成的url，可用于调用视觉智能开放平台的能力
print(oss_url)

Node.js SDK

推荐使用NPM工具安装依赖包。最低环境要求Node 8.x以上，如不满足SDK版本所需环境要求请升级Node版本。

npm install @alicloud/viapi-utils@^1.0.0 --save

JavaScript代码示例如下。

const ViapiUtil = require('@alicloud/viapi-utils');
// 创建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。运行示例前必须先配置环境变量。
let accessKeyId =  process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
let accessKeySecret = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
// 场景一，使用本地文件
let file = "/tmp/bankCard.png";
// 场景二，使用任意可访问的url
// let file = "https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg";
ViapiUtil.default.upload(accessKeyId, accessKeySecret, file)
  .then(function(ossUrl) {
    // 生成的url，可用于调用视觉智能开放平台的能力
    console.log(ossUrl);
  })
  .catch(function(err) {
    console.log(err);
  });

TypeScript代码示例如下。

import ViapiUtil from '@alicloud/viapi-utils';
export default class Client {
  static async main(): Promise<void> {
    // 创建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。运行示例前必须先配置环境变量。
    let accessKeyId: string = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
    let accessKeySecret: string = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
    // 场景一，使用本地文件
    let file: string = "/tmp/bankCard.png";
    // 场景二，使用任意可访问的url
    // let file: string = "https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg";
    let ossUrl: string = await ViapiUtil.upload(accessKeyId, accessKeySecret, file);
    // 生成的url，可用于调用视觉智能开放平台的能力
    console.log(ossUrl);
  }
}
Client.main();

PHP SDK

推荐使用composer工具安装依赖包。最低环境要求PHP 5.6，如不满足SDK版本所需环境要求请升级PHP版本。（暂不支持PHP 8）

composer require alibabacloud/viapi-utils

具体代码示例如下。

<?php
namespace Alibabacloud\SDK;
use AlibabaCloud\SDK\ViapiUtils\ViapiUtils;
class Client {
    public static function main() {
        // 创建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。运行示例前必须先配置环境变量。    
        $accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');      
        $accessKeySecret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');
        // 场景一，使用本地文件
        // $file = "/tmp/bankCard.png";
        // 场景二，使用任意可访问的url
        $file = "https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg";
        $ossUrl = ViapiUtils::upload($accessKeyId, $accessKeySecret, $file);
        // 生成的url，可用于调用视觉智能开放平台的能力
        echo $ossUrl;
    }
}
// 引入autoload.php
$path = __DIR__ . \DIRECTORY_SEPARATOR . '..' . \DIRECTORY_SEPARATOR . 'vendor' . \DIRECTORY_SEPARATOR . 'autoload.php';
if (file_exists($path)) {
    require_once $path;
}
Client::main(array_slice($argv, 1));

Go SDK

推荐使用Go工具安装依赖包。最低环境要求必须不低于Go 1.15.x，如不满足SDK版本所需环境要求请升级Go版本。

go get github.com/alibabacloud-go/viapi-utils/client

具体代码示例如下。

package main
import (
    "fmt"
    "github.com/alibabacloud-go/tea/tea"
    viapiutil "github.com/alibabacloud-go/viapi-utils/client"
)
func main() {
    // 场景一，使用本地文件
    file := tea.String("/tmp/bankCard.png")
    // 场景二，使用任意可访问的url
    // file := tea.String("https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg")
    // 上传成功后，返回上传后的文件地址

    // 创建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。运行示例前必须先配置环境变量。
    ossUrl, _err := viapiutil.Upload(tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")), tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")), file)
    if _err != nil {
        fmt.Println(_err)
    }
    // 生成的url，可用于调用视觉智能开放平台的能力
    fmt.Println(*ossUrl)
}

.NET SDK

推荐使用Nuget工具安装依赖包。最低环境要求net framework 4.5或.Net Core 2.0，如不满足SDK版本所需环境要求请升级.NET版本。

dotnet add package AlibabaCloud.SDK.VIAPIUtils

具体代码示例如下。

using System;
// dotnet add package AlibabaCloud.SDK.VIAPIUtils
using AlibabaCloud.SDK.VIAPI.Utils;
namespace viapitest
{
    class Program
    {
        static void Main(string[] args)
        {
            // 场景一，使用本地文件
            // string file = "/tmp/bankCard.png";
            // 场景二，使用任意可访问的url
            string file = "https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg";
            // 创建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。运行示例前必须先配置环境变量。
            FileUtils fileobj = FileUtils.getInstance(Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"), Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            string ossUrl = fileobj.Upload(file);
            // 生成的url，可用于调用视觉智能开放平台的能力
            Console.WriteLine(ossUrl);
        }
    }
}

其他语言

如果非以上6种语言，您可以自行实现viapiutils的相关逻辑，具体操作步骤如下：

调用GetOssStsToken接口获取临时的OSS STS Token，该Token建议在后续业务一次性使用。具体操作，请参见请求签名。

接口Action：GetOssStsToken
接口版本号：2020-04-01
域名：viapiutils.cn-shanghai.aliyuncs.com
无业务参数
返回数据

名称	类型	示例值	描述
AccessKeyId	String	STS.NTT2MimJtnhtStr14rzky****	STS临时Token的AccessKeyID字段。
AccessKeySecret	String	9VoH2Q5s286TaA9yyfZHqXWezdq5qK4i6auR2Vd5****	STS临时Token的AccessKeySecret字段。
SecurityToken	String	CAIShwN1q6Ft5B2yfSjIr5fh****...	STS临时Token的SecurityToken字段。

使用临时的OSS STS Token，将文件上传到阿里云视觉智能开放平台官方OSS Bucket。具体操作，请参见OSS SDK示例。
使用OSS STS Token上传文件到阿里云视觉智能开放平台官方OSS Bucket，需要注意以下几点：
1. 上传用到的OSS Bucket地域固定为cn-shanghai。
2. 上传用到的OSS Bucket名固定为viapi-customer-temp。
3. 上传的路径前缀必须是您在步骤1中调用接口时所使用的AccessKeyId。
  例如，您在步骤1调用时用到的AccessKeyId为LTAxxxxxxxabc，此时传到OSS后的地址路径应该类似：LTAxxxxxxxabc/<uuid>/test.jpg。为了文件不相互覆盖，建议您在路径中加上<uuid>作为区分。
完成上传后可获取到OSS的URL地址，该地址用于后续接口请求。
地址路径应类似如下示例：
```
http://viapi-customer-temp.oss-cn-shanghai.aliyuncs.com/LTAxxxxxxxabc/<uuid>/test.jpg
```
说明
该地址无法在浏览器直接打开或者直接访问，您可以用它作为文件URL参数调用阿里云视觉智能开放平台的算法。

此处以银行卡识别（RecognizeBankCard）为例，为您介绍不同场景下如何实现viapiutils逻辑，调用其他算法接口请参考注释修改代码。