首页 > 营销学院 > 技术知识

Cloudinary REST API 图片销毁指南：正确生成请求签名

本文旨在解决使用 cloudinary rest api 销毁图片时常见的签名生成问题。核心在于，api 请求的签名必须包含除 `file`、`cloud_name`、`resource_type` 和 `api_key` 之外的所有请求参数。这些参数需按字母顺序排列，并与 `api_secret` 拼接后进行 sha-1 哈希。掌握正确的签名生成方法是确保图片成功销毁的关键。

引言：Cloudinary REST API 图片销毁概览

Cloudinary 作为一个强大的云媒体管理平台，提供了丰富的 API 接口，允许开发者对图片、视频等媒体资源进行上传、转换、管理和销毁。在使用其 REST API 执行敏感操作，例如销毁（destroy）图片时，为了确保请求的安全性与合法性，Cloudinary 强制要求对请求进行签名验证。正确的签名是 API 调用成功的关键，而签名生成不当则是导致操作失败的常见原因。本文将详细阐述 Cloudinary REST API 销毁图片时签名生成的正确方法，并提供完整的 PHP 代码示例。

理解 Cloudinary API 签名机制

Cloudinary 的 API 签名机制是其安全模型的核心组成部分。当您通过 REST API 发送请求时，除了 api_key 之外，还需要提供一个 signature 参数。这个签名是根据特定的请求参数和您的 api_secret 生成的，用于验证请求的真实性，防止未经授权的访问和数据篡改。

签名生成的基本规则：

包含所有相关参数： 除了 file、cloud_name、resource_type 和 api_key 之外，所有作为请求一部分发送的参数都必须包含在用于生成签名的字符串中。
参数按字母顺序排列： 在构造用于签名的字符串时，所有待签名的参数（及其值）必须按照参数名的字母顺序进行排列。
拼接 api_secret： 排列好的参数字符串需要与您的 api_secret 进行拼接。
进行 SHA-1 哈希： 最后，对拼接后的完整字符串进行 SHA-1 哈希运算，生成最终的 signature。

常见错误：签名参数遗漏

许多开发者在使用 Cloudinary REST API 时，可能会遇到图片销毁失败的问题，且 API 返回结果为空或报错。这通常是由于签名生成过程中遗漏了部分请求参数所致。

例如，在尝试销毁图片时，如果请求中包含了 public_id、timestamp 和 invalidate 等参数，但签名生成时只考虑了 timestamp，那么 Cloudinary 服务器在验证签名时就会发现不匹配，从而拒绝该请求。

错误的签名生成示例（仅签名 timestamp）：

// 假设 $public_id 和 $invalidate 也在请求中发送
$signature = sha1("timestamp=".$timestamp.$api_secret); 
// 错误：遗漏了 public_id 和 invalidate 参数

这种情况下，尽管 api_key 和 timestamp 都正确，但由于 public_id 和 invalidate 未被纳入签名计算，导致服务器认为签名无效。

正确生成 Cloudinary API 签名

要正确生成 Cloudinary API 签名，关键在于识别所有需要签名的参数，并严格按照字母顺序进行排列。

以下是针对图片销毁操作（包含 public_id 和 invalidate 参数）的正确签名生成步骤：

步骤一：识别待签名参数

在销毁图片的场景中，常见的待签名参数包括：

public_id：要销毁的图片的公共 ID。
timestamp：请求的时间戳。
invalidate：一个布尔值，指示是否从 CDN 缓存中清除该图片（通常设置为 true）。

步骤二：参数按字母顺序排列

将这些参数及其值组合成键值对字符串，并按照参数名的字母顺序排列：

invalidate=true
public_id=folder/sample_public_id (请替换为实际的公共 ID)
timestamp=1678886400 (请替换为实际的时间戳)

拼接后形成一个查询字符串形式的参数列表：

invalidate=true&public_id=folder/sample_public_id×tamp=1678886400

步骤三：拼接参数与 api_secret

将上述排序好的参数字符串与您的 api_secret 拼接起来。

"invalidate=true&public_id=folder/sample_public_id×tamp=".$timestamp.$api_secret

步骤四：进行 SHA-1 哈希

最后，对拼接后的字符串进行 SHA-1 哈希运算，得到最终的 signature。

修正后的 PHP 签名代码示例：

$api_key = "YOUR_API_KEY"; // 替换为您的 Cloudinary API Key
$api_secret = "YOUR_API_SECRET"; // 替换为您的 Cloudinary API Secret
$cloud_name = "YOUR_CLOUD_NAME"; // 替换为您的 Cloudinary Cloud Name

$public_id_to_destroy = "folder/sample_public_id"; // 替换为要销毁的图片公共 ID
$timestamp = time(); // 当前时间戳

// 注意：这里需要将所有参与 POST 请求的参数（除了api_key, resource_type, cloud_name, file）都纳入签名
// 且参数需要按字母顺序排列
$params_to_sign = array(
    'invalidate' => 'true', // 注意：布尔值在签名时通常以字符串形式出现
    'public_id' => $public_id_to_destroy,
    'timestamp' => $timestamp
);

// 对参数进行字母排序
ksort($params_to_sign);

// 拼接参数字符串
$signature_string = '';
foreach ($params_to_sign as $key => $value) {
    $signature_string .= $key . '=' . $value . '&';
}
// 移除最后一个 '&'
$signature_string = rtrim($signature_string, '&');

// 拼接 api_secret 并进行 SHA-1 哈希
$signature = sha1($signature_string . $api_secret);

// 最终的签名字符串将类似于: sha1("invalidate=true&public_id=folder/sample_public_id&timestamp=1678886400YOUR_API_SECRET")

完整的 PHP 图片销毁示例

结合上述正确的签名生成方法，以下是一个使用 cURL 发送 Cloudinary 图片销毁请求的完整 PHP 示例：

<?php

// Cloudinary 凭据，请替换为您的实际信息
$api_key = "YOUR_API_KEY";
$api_secret = "YOUR_API_SECRET";
$cloud_name = "YOUR_CLOUD_NAME"; // 替换为您的 Cloudinary Cloud Name

// 要销毁的图片公共 ID，包含路径（如果存在）
$public_id_to_destroy = "folder/sample_public_id";

// 获取当前时间戳
$timestamp = time();

// 准备需要签名的参数
$params_to_sign = array(
    'invalidate' => 'true', // 销毁后从 CDN 缓存中清除
    'public_id' => $public_id_to_destroy,
    'timestamp' => $timestamp
);

// 对参数进行字母排序
ksort($params_to_sign);

// 拼接参数字符串
$signature_string = '';
foreach ($params_to_sign as $key => $value) {
    $signature_string .= $key . '=' . $value . '&';
}
$signature_string = rtrim($signature_string, '&'); // 移除末尾的 '&'

// 生成签名
$signature = sha1($signature_string . $api_secret);

// 准备 POST 请求的数据
$postRequest = array(
    'public_id' => $public_id_to_destroy,
    'timestamp' => $timestamp,
    'api_key' => $api_key,
    'signature' => $signature,
    'resource_type' => 'image', // 指定资源类型为图片
    'invalidate' => true // 销毁后从 CDN 缓存中清除
);

// 初始化 cURL
$ch = curl_init();

// 设置 cURL 请求 URL
curl_setopt($ch, CURLOPT_URL, "https://api.cloudinary.com/v1_1/{$cloud_name}/image/destroy");
// 设置为 POST 请求
curl_setopt($ch, CURLOPT_POST, 1);
// 设置 POST 请求体
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postRequest));
// 如果 HTTP 状态码表示错误，则返回 FALSE
curl_setopt($ch, CURLOPT_FAILONERROR, true);
// 允许 cURL 跟踪重定向
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
// 开启详细输出（用于调试）
// curl_setopt($ch, CURLOPT_VERBOSE, true); 
// 将服务器响应作为字符串返回，而不是直接输出
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// 禁用 SSL 主机验证和对等验证（生产环境不推荐，仅用于测试）
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
// 设置连接超时和请求超时
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 3);
curl_setopt($ch, CURLOPT_TIMEOUT, 20);

// 执行 cURL 请求
$response = curl_exec($ch);

// 检查是否有 cURL 错误
if (curl_errno($ch)) {
    echo 'cURL Error: ' . curl_error($ch);
} else {
    // 打印服务器响应
    print_r($response);
}

// 关闭 cURL 资源
curl_close($ch);

?>

代码说明：

$cloud_name：您的 Cloudinary 云名称。
$public_id_to_destroy：您希望销毁的图片的公共 ID。请确保该 ID 包含任何文件夹路径（例如 folder/sample_public_id）。
$timestamp：使用 time() 函数获取当前 Unix 时间戳。
$params_to_sign 数组：包含了所有需要签名的参数。注意 invalidate 的值在这里是字符串 'true'，以确保与 Cloudinary 签名规则一致。
ksort($params_to_sign)：对数组进行键名排序，确保参数按字母顺序排列。
http_build_query($postRequest)：将关联数组转换为 URL 编码的查询字符串，作为 POST 请求体发送。
CURLOPT_FAILONERROR 和 CURLOPT_RETURNTRANSFER：这两个选项对于捕获 API 错误和处理响应至关重要。

注意事项与最佳实践

错误处理： 在生产环境中，务必对 curl_exec($ch) 的返回值进行严格检查，并利用 curl_errno($ch) 和 curl_error($ch) 获取详细的错误信息，以便及时发现并解决问题。Cloudinary API 也会在响应中提供错误详情。
invalidate 参数： 当 invalidate 设置为 true 时，Cloudinary 会尝试从其 CDN 缓存中清除被销毁的图片。这对于确保图片立即从所有分发点消失非常重要。
public_id 的准确性： 销毁操作要求 public_id 精确无误。如果图片位于某个文件夹中，public_id 必须包含完整的文件夹路径（例如 my_folder/my_image）。
API Secret 安全： 您的 api_secret 是敏感凭据，绝不能暴露在客户端代码或公共仓库中。应始终在服务器端进行 API 调用。

使用官方 SDK： Cloudinary 提供了多种语言的官方 SDK（如 PHP、Python、Node.js、J*a 等）。这些 SDK 通常会自动处理签名生成、错误处理和各种 API 调用的复杂性，强烈建议在实际项目中优先使用 SDK，以简化开发并减少出错的可能性。例如，使用 Cloudinary PHP SDK 销毁图片的代码会更简洁：

require 'vendor/autoload.php'; // 如果使用 Composer
use Cloudinary\Cloudinary;
use Cloudinary\Configuration\Configuration;

Configuration::instance([
    'cloud_name' => 'YOUR_CLOUD_NAME',
    'api_key' => 'YOUR_API_KEY',
    'api_secret' => 'YOUR_API_SECRET'
]);

$cloudinary = new Cloudinary();
try {
    $result = $cloudinary->upload_api()->destroy('folder/sample_public_id', ['resource_type' => 'image', 'invalidate' => true]);
    print_r($result);
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

总结

正确生成 Cloudinary REST API 请求的签名是确保图片销毁操作成功的关键。核心在于理解签名机制，即除了少数特定参数外，所有请求参数都必须按字母顺序排列并与 api_secret 一同进行 SHA-1 哈希。通过遵循本文提供的指南和代码示例，您可以有效地解决签名问题，并可靠地管理 Cloudinary 上的媒体资源。在实际开发中，推荐使用 Cloudinary 官方 SDK 来简化 API 交互并提高代码的健壮性。

以上就是Cloudinary REST API 图片销毁指南：正确生成请求签名的详细内容，更多请关注php中文网其它相关文章！

# python # php # 解决问题 # 设置为 # 顺序排列 # 您的 # unix # ai # curl # ssl # 编码 # composer # node # node.js # js # java # 并与 # 外部图片 seo # 日照抖音关键词排名优化 # 药品技术推广与营销论文 # 孝感爱采购seo排名 # 寻乌保安公司网络营销推广 # 在这里 # 是一个 # 移除 # 发点 # 怎么看 # 品牌企业网站建设服务 # 绍兴营销推广加盟店电话 # 新乡网站优化工程师 # 金昌网站营销推广 # 抖音快手短视频推广营销

相关栏目：【 Google疑问12 】【 Facebook疑问10 】【优化推广96088 】【技术知识133117 】【 IDC资讯59369 】【网络运营7196 】【 IT资讯61894 】

2025-11-19

SQL多表关联如何理解_核心原理解析助你掌握关键方法【教程】 SQL多表连接如何理解_JOIN关联关系详细步骤解析【指导】 SQL多表连接结果异常怎么办_JOIN条件排查方法解析【指导】 SQL索引下推是什么_ICP机制性能提升原理【教程】 SQL跨表统计怎么写_重要技巧总结提升查询效率【技巧】 SQL注入如何防护_完整逻辑拆解助力系统化掌握【技巧】 SQL上传文件信息建模方法_SQL存储文件元数据方案 SQL多语种存储方案设计_SQL字符集选择策略 SQL字符串处理如何编写_重要技巧总结提升查询效率【教学】 SQL去重查询怎么实现_优化思路讲解帮助高效处理数据【技巧】 SQL统计复购用户怎么做_多次行为分析SQL思路【教程】 SQL字符串处理如何编写_优化思路讲解帮助高效处理数据【教程】 SQL动态字段解析技巧_SQL解析JSON多层字段 SQL线上慢SQL如何治理_规范与工具实践总结【技巧】 SQL表结构如何演进_兼容老数据设计思路【教程】 SQL排序规则如何设置_ORDERBY排序原理与性能说明【指导】 SQL去重查询怎么实现_真实案例解析强化复杂查询思维【教学】 SQL按字段范围分批处理_SQL避免长时间锁表 SQL统计不同字段组合数量_多列聚合查询技巧【技巧】 SQL多字段去重怎么处理_GROUPBY去重思路说明【教学】

了解您产品搜索量及市场趋势，制定营销计划

同行竞争及网站分析保障您的广告效果

点击免费数据支持

提交您的需求，1小时内享受我们的专业解答。

运城市盐湖区信雨科技有限公司

运城市盐湖区信雨科技有限公司是一家深耕海外推广领域十年的专业服务商，作为谷歌推广与Facebook广告全球合作伙伴，聚焦外贸企业出海痛点，以数字化营销为核心，提供一站式海外营销解决方案。公司凭借十年行业沉淀与平台官方资源加持，打破传统外贸获客壁垒，助力企业高效开拓全球市场，成为中小企业出海的可靠合作伙伴。