文档

文件URL处理

更新时间:

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

背景信息

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

说明

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

场景一:上海地域OSS文件

  1. 登录OSS管理控制台

  2. 创建存储空间

    创建Bucket选择区域时,需要选择与视觉智能开放平台对应服务能力相同的区域,当前视觉智能开放平台各服务支持的区域为华东2(上海)

    说明

    如果您的OSS所在地域不是华东2(上海),请参见场景二:非上海地域OSS文件进行调用。

  3. 上传本地文件到OSS服务。

    具体操作请参见上传文件

  4. 查看文件URL。

    在已上传图片列表中,单击详情查看并复制图片URL。

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

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

配置环境变量

配置环境变量ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_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_IDALIBABA_CLOUD_ACCESS_KEY_SECRET,并写入已准备好的AccessKey ID和AccessKey Secret。然后重启Windows系统。本操作以Windows 10为例进行说明。

    1. 打开文件资源管理器,在此电脑上右键单击属性。

    2. 在右侧导航栏,单击高级系统配置

    3. 系统属性对话框的高级页签下,单击环境变量

    4. 环境变量对话框中,单击新建(W)image.png

    5. 在弹出的新建系统变量对话框中,添加环境变量ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_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的相关逻辑,具体操作步骤如下:

  1. 调用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字段。

  2. 使用临时的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>作为区分。

  3. 完成上传后可获取到OSS的URL地址,该地址用于后续接口请求。

    地址路径应类似如下示例:

    http://viapi-customer-temp.oss-cn-shanghai.aliyuncs.com/LTAxxxxxxxabc/<uuid>/test.jpg
    说明

    该地址无法在浏览器直接打开或者直接访问,您可以用它作为文件URL参数调用阿里云视觉智能开放平台的算法。

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