Tinify Java API中文参考文档

自己刚用Tinify Java写了一个批处理压缩图片的程序，所以想着顺带把这个教程给翻译了。最后发现翻译还是挺花时间的。自己写程序的时候，只是简单看看就明白，用api就可以直接写程序了。而且现在翻译软件很强大，用来开发看是够用了。翻译就不一样了，有些语句还得斟酌一样，排版一下，用翻译软件帮忙了，最后花的时间比自己写的程序还多。

翻译文章原地址：https://api.tinify.com/developers/reference/java
有些内容我是按照自己的理解写的，质量不敢保证，但是用这个教程还真的是很容易用java写出使用tinify压缩图片的程序来。

Tinify API允许您压缩和优化JPEG与PNG图像。 它是基于Rest服务设计的（轻量级web服务）。我们维护各种语言的客户端库，使其与Tinify API进行交互变得非常简单。

安装

您可以在Java客户端的pom.xml配置文件中添加以下内容作为Maven依赖关系。为了避免在更新客户端时破坏代码的更改，请将RELEASE替换为特定版本：

<dependency>
  <groupId>com.tinify</groupId>
  <artifactId>tinify</artifactId>
  <version>RELEASE</version>
</dependency>

如果您使用Gradle，则可以使用以下内容：

dependencies { 
    compile 'com.tinify:tinify:latest.release'
}

源代码可在Github上获取使用。

认证(Authentication)

要使用API，您必须提供您的API密钥。 您可以通过注册您的姓名和电子邮件地址获取API密钥。 请始终秘密保存您的API密钥！

import com.tinify.*; 

public class Example { 
    public static void main(String[] args) { 
        Tinify.setKey("YOUR_API_KEY"); 
    } 
}

所有请求将通过加密的HTTPS连接进行。

您可以使用API客户端通过HTTP代理发出所有请求。 设置代理服务器的URL和账户有密码。

Tinify.setProxy("http://user:pass@192.168.0.1:8080");

压缩图像

您可以将任何JPEG或PNG图像上传到Tinify API进行压缩。 我们将自动检测图像的类型，并相应地使用TinyPNG或TinyJPG引擎进行优化。 一旦您上传文件或提供该图像的URL，压缩将立即开始。

您可以选择本地文件作为源，并将其写入另一个文件。

Source source = Tinify.fromFile("unoptimized.jpg");
source.toFile("optimized.jpg");

您还可以从缓冲区（带二进制字符串）上传图像，并获取压缩的图像数据。

byte[] sourceData = Files.readAllBytes(Paths.get("unoptimized.jpg"));
byte[] resultData = Tinify.fromBuffer(sourceData).toBuffer();

您可以提供一个URL到您的图像，而不必上传它。

Source source = Tinify.fromUrl("https://cdn.tinypng.com/images/panda-happy.png"); 
source.toFile("optimized.jpg");

调整图像大小

使用API创建已上传图像的已更改版本。 通过让API句柄调整大小，您可以避免自己编写这样的代码，您只需要上传一次图像。 调整大小的图像将被优化压缩与美丽和脆弱的外观。

您还可以利用智能裁剪创建专注于图像最重要视觉领域的缩略图。

调整大小计数作为一个额外的压缩。 例如，如果您上传单个图像并检索优化版本加上2个缩放版本，则这将总计为3次压缩。

要调整图像大小，请调用图像源上的resize方法：

Source source = Tinify.fromFile("large.jpg"); 
Options options = new Options() 
    .with("method", "fit") 
    .with("width", 150) 
    .with("height", 100); 
Source resized = source.resize(options); 
resized.toFile("thumbnail.jpg");

该方法描述您的图像的大小调整方式。 以下方法可用：

scale

按比例缩放图像。 您必须提供目标宽或高，但不能同时提供宽和高。 缩放图像能够自动缩放另外的宽或者高。

fit

按比例缩放图像，使其符合给定的尺寸。 您必须同时提供宽度和高度。 缩放图像不会超过这些尺寸。

cover

按比例缩放图像，并在必要时对其进行裁剪，以使结果具有给定的尺寸。 您必须同时提供宽度和高度。 自动确定图像的哪些部分被裁剪掉。 一个智能算法确定最重要的区域，并保留完整。

如果目标尺寸大于原始尺寸，则图像将不会放大。 为了保护图像的质量，防止缩放。

保存元数据(Preserving metadata)

您可以请求将特定元数据从上传的图像复制到压缩版本。 保留版权信息，当前支持GPS位置和创建日期。 保留元数据会增加压缩文件的大小，因此您应该只保留重要的元数据。

保留元数据不会被视为额外的压缩。 但是，在后台，将再次使用附加元数据创建映像。

要保留特定的元数据，请调用图像源上的preserve方法：

Source source = Tinify.fromFile("large.jpg"); 
Source copyrighted = source.preserve("copyright", "creation"); copyrighted.toFile("optimized-copyright.jpg");

您可以提供以下选项来保留特定的元数据。 如果请求的元数据不存在于上传的图像中，则不会添加元数据。

版权(copyright)
保留任何版权信息。 这包括EXIF版权标签（JPEG），XMP版权标记（PNG）以及Photoshop版权标志或网址。 使用多达90个附加字节，加上版权数据的长度。

创作(creation)（仅限JPEG）
保存任何创建日期或时间。 这是图像或照片最初创建的时刻。 这包括EXIF原始日期时间标签（JPEG）。 使用大约70个额外的字节。

位置(location )（仅限JPEG）
保留描述图像或照片拍摄位置的任何GPS位置数据。 这包括EXIF GPS纬度和GPS经度标签（JPEG）。 使用大约130个附加字节。

保存到Amazon S3

您可以告诉Tinify API将压缩图像直接保存到Amazon S3。 如果您使用S3托管您的图像，这将节省您将图像下载到您的服务器并将其自己上传到S3的麻烦。

要将图像保存到S3，请在图像源上调用store方法：

Source source = Tinify.fromFile("large.jpg"); 
Options options = new Options() .with("service", "s3") 
    .with("aws_access_key_id", "AKIAIOSFODNN7EXAMPLE")
    .with("aws_secret_access_key", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
    .with("region", "us-west-1") 
    .with("path", "example-bucket/my-images/optimized.jpg");
source.store(options);

您需要提供以下选项才能在Amazon S3上保存图像：

服务端必须是在s3，目前只支持Amazon S3。

aws_access_key_id
aws_secret_access_key

您的AWS访问密钥ID和密钥访问密钥。 这些是登录Amazon AWS用户帐户的凭据。 了解如何在Amazon的文档中获取它们。

用户必须具有正确的权限，详情请见下文。

地区
您的S3所在的AWS区域。

路径
您要存储图像的路径，包括桶名称。 路径必须以以下格式提供：

<bucket> / <path> / <filename>。

与您的AWS访问密钥ID相对应的用户必须在要创建的对象的路径上具有PutObject和PutObjectAcl权限。
S3访问策略的例子

如果要为Tinify API创建具有有限访问权限的用户，则可以使用以下示例策略作为起点：

{ "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:PutObject",
      "s3:PutObjectAcl"
    ],
    "Resource": [
      "arn:aws:s3:::example-bucket/*"
    ]
  }
}

错误处理

Tinify API使用HTTP状态代码来指示成功或失败。任何HTTP错误都将转换为异常，由客户端库抛出。

有四种不同类型的错误。异常消息将包含更详细的错误条件描述。

AccountException
您的API密钥或您的API帐户有问题。您的请求无法授权。如果达到压缩限制，您可以等到下一个日历月或升级您的订阅。验证您的API密钥和您的帐户状态后，您可以重试该请求。

ClientException
由于提交的数据有问题，请求无法完成。异常消息将包含更多信息。您不应该重试请求。

ServerException
由于Tinify API暂时出现问题，请求无法完成。在几分钟后重试该请求是安全的。如果反复出现此错误较长时间，请与我们联系。

ConnectionException
无法发送请求，因为连接到Tinify API有问题。您应该验证您的网络连接。重试请求是安全的。

您可以分别处理每种类型的错误：

try { 
    // Use the Tinify API client. 
} catch(AccountException e) { 
    System.out.println("The error message is: " + e.getMessage()); 
    // Verify your API key and account limit.
} catch(ClientException e) {
    // Check your source image and request options. 
} catch(ServerException e) { 
    // Temporary issue with the Tinify API. 
} catch(ConnectionException e) { 
    // A network connection error occurred. 
} catch(java.lang.Exception e) { 
    // Something else went wrong, unrelated to the Tinify API. 
}

如果您正在编写使用用户配置的API密钥的代码，则可能需要在尝试压缩图像之前验证API密钥。 该验证产生一个虚拟请求来检查网络连接并验证API密钥。 如果虚拟请求失败，则抛出错误。

try { 
    Tinify.setKey("YOUR_API_KEY"); Tinify.validate();
} catch(java.lang.Exception e) {
    // Validation of API key failed. 
}

压缩数

API客户端会自动跟踪您在本月做的压缩次数。 验证您的API密钥后或至少做出一个压缩请求后，您可以获得压缩计数。

int compressionsThisMonth = Tinify.compressionCount();

需要帮忙或者有反馈

我们永远在这里帮助，所以如果你坚持只是在[email protected]上给我们留言。 这也是向我们发送您所有建议和反馈的完美地点。