akeneo 作为一款领先的 pim（产品信息管理）系统，允许用户为产品关联各种媒体资产，如图片、视频、文档等。在与外部系统集成或进行数据导出时，程序化地获取这些媒体资产变得至关重要。本文将重点讲解如何通过 akeneo php api 客户端（akeneo/api-php-client-ee）来获取并下载特定产品的媒体文件。
理解 Akeneo 媒体资产的结构
在 Akeneo 中，媒体资产通常通过“资产家族（Asset Family）”进行管理。一个产品可以关联一个或多个资产家族下的资产。当产品关联了某个资产时，其数据中会包含一个资产代码，这个代码是资产在 Akeneo 系统中的唯一标识符。仅仅获取到这个资产代码并不足以直接下载文件，我们还需要进一步查询该资产的详细信息，包括其关联的实际媒体文件标识符，然后才能进行下载。
使用 Akeneo PHP API 客户端获取媒体资产
获取产品媒体资产主要涉及两个 Akeneo API 客户端服务：
- ProductApi: 用于查询产品信息，从中提取关联的资产代码。
- AssetManagerApi: 根据资产家族代码和资产代码，获取资产的详细信息，包括其内部存储的媒体文件标识符。
- AssetMediaFileApi: 根据媒体文件标识符，下载具体的媒体文件。
下面我们将通过一个具体的 PHP 代码示例来演示整个流程。
1. 初始化 Akeneo API 客户端
首先，确保您已经正确安装并配置了 Akeneo PHP API 客户端。以下是一个简化的客户端初始化示例（请根据您的实际配置替换占位符）：
立即学习“PHP免费学习笔记（深入）”；
use Akeneo\Pim\ApiClient\AkeneoPimClientBuilder;
// 假设您已经有了Akeneo实例的URL、客户端ID、密钥、用户名和密码
$clientBuilder = new AkeneoPimClientBuilder('YOUR_AKENEO_URL');
$client = $clientBuilder->buildAuthenticatedByPassword(
'YOUR_CLIENT_ID',
'YOUR_CLIENT_SECRET',
'YOUR_USERNAME',
'YOUR_PASSWORD'
);2. 查询产品并提取资产代码
接下来，我们需要查询产品，并从产品数据中找到关联的资产代码。产品数据通常包含一个 values 字段，其中可能有一个名为 assets 的属性，它会列出产品关联的资产信息。
// 构建搜索条件，例如获取所有已启用的产品
$searchBuilder = new \Akeneo\Pim\ApiClient\Search\SearchBuilder();
$searchBuilder->addFilter('enabled', '=', true);
$searchFilters = $searchBuilder->getFilters();
// 分页获取产品，这里每次获取100个
$products = $client->getProductApi()->all(100, ['search' => $searchFilters]);
foreach ($products as $product) {
echo "处理产品: " . ($product['identifier'] ?? '未知') . "\n";
// 检查产品是否有 'assets' 属性
if (isset($product['values']['assets'])) {
foreach ($product['values']['assets'] as $assetData) {
// assetData['data'] 包含了资产代码
foreach ($assetData['data'] as $assetCode) {
echo " 发现资产代码: " . $assetCode . "\n";
// 接下来处理这个资产代码
// ...
}
}
}
}3. 获取资产详情并下载媒体文件
获取到资产代码后，我们不能直接用它来下载文件。我们需要使用 AssetManagerApi 来获取该资产的详细信息。在 Akeneo 的管理界面中，您会看到资产家族的概念（例如，"bilder" 可能是一个资产家族代码，代表图片）。这个资产家族代码是调用 getAssetManagerApi()->get() 方法时的关键参数。
资产详情会包含一个 values 字段，其中可能包含不同类型的媒体属性，例如 media、variation_image 等。这些属性的 data 字段才是真正用于 AssetMediaFileApi 下载的媒体文件标识符。
// 假设我们正在上面foreach ($products as $product) 循环内部
foreach ($products as $product) {
// ... (前略，获取产品和资产代码)
if (isset($product['values']['assets'])) {
foreach ($product['values']['assets'] as $assetAttributeCode => $assetData) {
foreach ($assetData['data'] as $assetCode) {
echo " 处理资产代码: " . $assetCode . "\n";
// 这里的 'bilder' 是一个示例资产家族代码。
// 您需要根据您的Akeneo配置替换为实际的资产家族代码。
// 如果一个产品关联了多个资产家族的资产，您可能需要更动态地确定资产家族代码。
// 通常，一个产品属性（如 $assetAttributeCode）会关联到一个特定的资产家族。
$assetFamilyCode = 'bilder'; // 示例：假设所有图片资产都属于 'bilder' 家族
try {
// 使用 AssetManagerApi 获取资产的详细信息
$assetsDetails = $client->getAssetManagerApi()->get($assetFamilyCode, $assetCode);
echo " 获取到资产详情 for code: " . $assetCode . "\n";
// 遍历资产详情中的所有媒体类型
foreach ($assetsDetails['values'] as $mediaType => $dataLines) {
foreach ($dataLines as $dataLine) {
if (isset($dataLine['data'])) {
$mediaFileIdentifier = $dataLine['data'];
echo " 发现媒体文件标识符 for type '{$mediaType}': " . $mediaFileIdentifier . "\n";
// 使用 AssetMediaFileApi 下载文件
$downloadResponse = $client->getAssetMediaFileApi()->download($mediaFileIdentifier);
// 获取文件内容
$fileContent = $downloadResponse->getBody();
// 构造本地保存路径和文件名
// basename() 用于从URL或路径中提取文件名
$fileName = basename($mediaFileIdentifier);
$localFilePath = '/tmp/' . $fileName; // 保存到 /tmp 目录
// 将文件内容写入本地文件
file_put_contents($localFilePath, $fileContent);
echo " 文件 '{$fileName}' 已下载到: {$localFilePath}\n";
}
}
}
} catch (\Akeneo\Pim\ApiClient\Exception\NotFoundHttpException $e) {
echo " 错误: 资产家族 '{$assetFamilyCode}' 下未找到资产 '{$assetCode}'。请检查资产家族代码和资产代码是否正确。\n";
} catch (\Exception $e) {
echo " 下载资产 '{$assetCode}' 时发生错误: " . $e->getMessage() . "\n";
}
}
}
} else {
echo " 产品 " . ($product['identifier'] ?? '未知') . " 没有关联资产。\n";
}
}完整代码示例：
buildAuthenticatedByPassword(
$clientId,
$clientSecret,
$username,
$password
);
echo "Akeneo API 客户端初始化成功。\n";
// --- 1. 查询产品 ---
$searchBuilder = new SearchBuilder();
// 示例：只获取已启用的产品，您可以根据需要添加其他过滤器
$searchBuilder->addFilter('enabled', '=', true);
$searchFilters = $searchBuilder->getFilters();
echo "开始查询产品...\n";
// 每次获取100个产品，您可以调整分页大小
$products = $client->getProductApi()->all(100, ['search' => $searchFilters]);
// --- 2. 遍历产品并处理其关联的资产 ---
foreach ($products as $product) {
$productIdentifier = $product['identifier'] ?? '未知产品';
echo "\n--- 处理产品: {$productIdentifier} ---\n";
if (isset($product['values']['assets'])) {
foreach ($product['values']['assets'] as $assetAttributeCode => $assetData) {
// $assetAttributeCode 可能是 'main_image', 'gallery_images' 等产品属性代码
// $assetData['data'] 是一个数组，包含一个或多个资产代码
foreach ($assetData['data'] as $assetCode) {
echo " 产品 '{$productIdentifier}' 关联资产代码: {$assetCode} (通过属性: {$assetAttributeCode})\n";
// --- 3. 获取资产详情并下载媒体文件 ---
// 这里的 'bilder' 是一个示例资产家族代码。
// 您需要根据您的 Akeneo 配置替换为实际的资产家族代码。
// 通常，一个产品属性 (如 $assetAttributeCode) 会关联到一个特定的资产家族。
// 在实际应用中，您可能需要一个映射关系来动态确定 $assetFamilyCode。
$assetFamilyCode = 'bilder'; // 假设所有图片资产都属于 'bilder' 家族
try {
// 使用 AssetManagerApi 获取资产的详细信息
$assetsDetails = $client->getAssetManagerApi()->get($assetFamilyCode, $assetCode);
echo " 成功获取资产 '{$assetCode}' 的详情。\n";
// 遍历资产详情中的所有媒体类型（例如 'media', 'variation_image' 等）
foreach ($assetsDetails['values'] as $mediaType => $dataLines) {
foreach ($dataLines as $dataLine) {
if (isset($dataLine['data'])) {
$mediaFileIdentifier = $dataLine['data'];
echo " 发现媒体文件标识符 for type '{$mediaType}': {$mediaFileIdentifier}\n";
// 使用 AssetMediaFileApi 下载文件
$downloadResponse = $client->getAssetMediaFileApi()->download($mediaFileIdentifier);
// 获取文件内容
$fileContent = $downloadResponse->getBody();
// 构造本地保存路径和文件名
// basename() 用于从URL或路径中提取文件名，确保文件名干净
$fileName = basename($mediaFileIdentifier);
$localDownloadDir = '/tmp/akeneo_downloads'; // 定义下载目录
if (!is_dir($localDownloadDir)) {
mkdir($localDownloadDir, 0777, true); // 创建目录如果不存在
}
$localFilePath = $localDownloadDir . '/' . $fileName;
// 将文件内容写入本地文件
file_put_contents($localFilePath, $fileContent);
echo " 文件 '{$fileName}' 已下载到: {$localFilePath}\n";
}
}
}
} catch (NotFoundHttpException $e) {
echo " 错误: 资产家族 '{$assetFamilyCode}' 下未找到资产 '{$assetCode}'。请检查资产家族代码和资产代码是否正确。\n";
} catch (\Exception $e) {
echo " 下载资产 '{$assetCode}' 时发生错误: " . $e->getMessage() . "\n";
}
}
}
} else {
echo " 产品 '{$productIdentifier}' 没有关联任何资产。\n";
}
}
echo "\n所有产品资产处理完毕。\n";
} catch (\Exception $e) {
echo "Akeneo API 客户端初始化或操作失败: " . $e->getMessage() . "\n";
exit(1);
}注意事项
- 资产家族代码（Asset Family Code）: 示例代码中使用了硬编码的 'bilder' 作为资产家族代码。在实际应用中，您需要根据您的 Akeneo 配置来确定正确的资产家族代码。一个产品属性（例如 main_image 或 gallery_images）通常会关联到一个特定的资产家族。您可能需要一个配置或映射来动态获取正确的资产家族代码。
- 媒体类型（Media Type）: assetsDetails['values'] 可能会包含多种媒体类型（如 media, variation_image 等），它们代表了资产的不同用途或变体。您的代码应遍历所有这些类型以确保获取所有相关文件。
- 错误处理: 代码中包含了 try-catch 块来捕获 NotFoundHttpException 和其他通用异常。在生产环境中，应加强错误日志记录和异常处理机制。
- 文件保存路径: 示例代码将文件保存到 /tmp/akeneo_downloads 目录。请确保该目录存在且 PHP 进程有写入权限，并根据您的需求调整保存路径。
- 文件名: basename($mediaFileIdentifier) 用于从 Akeneo 提供的媒体文件标识符中提取一个干净的文件名。在某些情况下，您可能需要根据产品 SKU 或其他信息来生成更具描述性的文件名，以避免文件名冲突。
- 性能考虑: 对于包含大量产品和资产的 Akeneo 实例，一次性获取所有产品可能会消耗大量内存和时间。请考虑使用分页、队列或增量同步等策略来优化性能。
总结
通过 Akeneo PHP API 客户端，您可以有效地访问和管理 Akeneo 中的产品媒体资产。关键在于理解 Akeneo 资产的层级结构：从产品中获取资产代码，然后通过资产家族代码和资产代码获取资产详情，最后使用媒体文件标识符下载实际文件。遵循本教程的指导和示例代码，您将能够成功地将 Akeneo 的媒体资产集成到您的应用程序或工作流中。
