Photoshop API v1 و Lightroom API تمام شدند؛ راهنمای مهاجرت به v2
Adobe در 31 ژوئیه 2026 Photoshop API v1 و Lightroom API را به پایان عمر رساند. اگر integration تصویری دارید، این راهنما دقیقاً نشان می دهد چه endpointها و payloadهایی تغییر کرده اند، کدام بخش ها در v2 یکپارچه شده اند و migration را چگونه بدون شکستن pipeline تولید انجام دهید.
31 ژوئیه برای Photoshop API v1 و Lightroom API چه معنی دارد؟
Adobe پایان عمر Photoshop API v1 و Lightroom API را برای 31 ژوئیه 2026 تعیین کرده است و توسعه دهندگانی که هنوز endpointهای قدیمی را صدا می زنند باید به Photoshop API v2 مهاجرت کنند. خود Adobe توصیه کرده migration پیش از اوت انجام شود تا اختلال سرویس رخ ندهد. نکته مهم این است که v2 صرفاً همان API با شماره نسخه جدید نیست؛ Adobe معماری Photoshop و Lightroom را در یک سطح واحد ادغام کرده، قرارداد request/response را تغییر داده و چند endpoint قدیمی را در endpointهای جامع تر جمع کرده است.
اگر integration شما فقط یک endpoint ساده را مصرف می کند، migration ممکن است کوچک به نظر برسد؛ اما سیستم هایی که pipeline ویرایش تصویر، polling job، storage خارجی، PSD manipulation یا چند عملیات Lightroom دارند باید contractها را دقیق بررسی کنند. بیشترین ریسک از جایی می آید که تیم فقط base URL را عوض کند و انتظار داشته باشد payload قبلی کار کند. مستندات رسمی صریحاً از breaking change در نام فیلدها، ساختار input/output، status response، کیفیت JPEG و compression PNG صحبت می کند.
v2 چه چیزی را یکپارچه کرده است؟
در v1، Photoshop و Lightroom مجموعه ای از endpointهای مجزا داشتند. برای Lightroom مثلاً autoTone، autoStraighten، presets، XMP و edit مسیرهای جداگانه بودند. در v2 این عملیات زیر /v2/edit جمع شده اند و می توانید چند adjustment را در یک request ترکیب کنید. برای document و layer نیز عملیات renditionCreate، documentCreate، documentOperations و smartObject عمدتاً به /v2/create-composite منتقل می شوند. Actions و convenience APIها هم به /v2/execute-actions می روند و status checking به /v2/status/{jobId} یکپارچه شده است.
| کار v1 | مسیر v2 | اثر روی migration |
|---|---|---|
| Lightroom autoTone / presets / XMP / edit | /v2/edit | چند adjustment را می توان در یک درخواست ترکیب کرد |
| renditionCreate / documentCreate / documentOperations / smartObject | /v2/create-composite | payload و مدل layerها بازطراحی شده است |
| photoshopActions / actionJSON / productCrop | /v2/execute-actions | Actions در یک قرارداد واحد جمع می شوند |
| Photoshop یا Lightroom status | /v2/status/{jobId} | polling و parsing پاسخ باید به مدل جدید منتقل شود |
این consolidation یک مزیت عملی دارد: orchestration سمت کلاینت می تواند ساده تر شود. در v1 برای چند adjustment پشت سر هم ممکن بود چند job بسازید و وضعیت هرکدام را poll کنید؛ v2 اجازه می دهد بخشی از این زنجیره در یک request اجرا شود. با این حال، migration را نباید با هدف «کمترین تغییر ممکن» انجام دهید. اگر endpoint جدید امکان کاهش round-trip و حذف glue code را می دهد، بهتر است معماری جدید را واقعاً استفاده کنید و adapter موقت v1 را برای همیشه نگه ندارید.
Breaking Changeهایی که بیشترین احتمال خطا دارند
| موضوع | v1 | v2 |
|---|---|---|
| Base URL | image*.adobe.io | photoshop-api*.adobe.io |
| Input URL | inputs[0].href | image.source.url |
| Output URL | outputs[0].href | outputs[0].destination.url |
| نوع خروجی | type | mediaType |
| JPEG quality | عدد | string enum مانند maximum |
| PNG compression | 3 سطح | 10 سطح |
| Authentication | OAuth Server-to-Server | بدون تغییر |
تغییر authentication نسبت به بقیه خبر خوبی است: Adobe می گوید credentialهای OAuth Server-to-Server فعلی قابل ادامه هستند. اما این موضوع نباید باعث شود migration را صرفاً transport-level ببینید. serializer و DTOهای شما احتمالاً با فیلدهای v1 ساخته شده اند. اگر strongly typed client دارید، بهتر است مدل های v2 را جدا بسازید و از reuse کردن classهای قبلی با چند JsonProperty alias پرهیز کنید؛ چون تفاوت فقط نام نیست و بعضی objectها مثل destination ساختار متفاوتی دارند.
در output format نیز تست regression ضروری است. اگر برنامه عدد 7 را برای JPEG quality ذخیره می کرد، v2 به string enum نیاز دارد. اگر UI یا config شما compression PNG را با سه مقدار مدل کرده، اکنون باید mapping جدید را تعریف کنید. این تغییرها ممکن است در compilation دیده نشوند اگر payload با dictionary یا JSON پویا ساخته شود؛ بنابراین integration testهایی که request واقعی را serialize و response واقعی را parse می کنند ارزش بیشتری از unit testهای صرف دارند.
Storage و URLهای ورودی/خروجی را دوباره طراحی کنید
v2 گزینه های خروجی منعطف تری برای embedded، hosted و external storage ارائه می دهد. این انعطاف خوب است، اما امنیت URLهای امضاشده و lifecycle آن ها باید در migration بررسی شود. اگر S3 یا storage سازگار را با presigned URL استفاده می کنید، TTL باید به اندازه زمان پردازش job باشد و permission فقط همان object لازم را پوشش دهد. URL ورودی را read-only و URL مقصد را write-only طراحی کنید و از reuse کردن credentialهای پهن دامنه برای pipeline پردازش تصویر خودداری کنید.
همچنین CDN یا proxy داخلی ممکن است روی hostnameهای v1 allowlist داشته باشد. تغییر base URL از image*.adobe.io به photoshop-api*.adobe.io می تواند در محیط staging کار کند ولی در production پشت egress firewall شکست بخورد. migration checklist باید DNS، egress policy، proxy، certificate inspection و observability را هم شامل شود. خطای network بعد از EOL از نظر کاربر تفاوتی با breaking payload ندارد، اما تیم troubleshooting اگر فقط کد را بررسی کند زمان زیادی از دست می دهد.
Layer و Document Operations؛ جایی که مهاجرت عمیق تر است
در عملیات composite و layer، v2 از image.source برای ورودی، edits برای عملیات و outputs برای نتیجه استفاده می کند. نام نوع layerها نیز از camelCase به snake_case تغییر کرده و operation.type برای add، edit، delete یا move صریح تر شده است. ترتیب پردازش edits.layers از بالا به پایین تعریف شده و قابلیت هایی مثل referenceLayer برای موقعیت نسبی و protection جزئی برای قفل کردن ویژگی های layer اضافه شده اند. برای سیستم هایی که PSD را برنامه وار می سازند، این بخش نیازمند test fixture واقعی است، نه فقط بررسی schema.
بهترین روش این است که مجموعه ای از فایل های نماینده production بسازید: PSD ساده، سند بزرگ، smart object، گروه layer، text layer با فونت، mask، clipping و چند output format. هر سناریو را در v1 و v2 اجرا کنید و نتیجه را از نظر ساختار document، ابعاد، layer order و فایل خروجی مقایسه کنید. اگر downstream سیستم شما hash یا اندازه فایل را فرض می کند، تغییر pipeline می تواند حتی با ظاهر یکسان خروجی اثر جانبی داشته باشد.
Actions، UXP و یک محدودیت مهم: Depth Blur
v2 مسیر /v2/execute-actions را برای انواع action یکپارچه کرده است و علاوه بر Photoshop Actions و ActionJSON، UXP script را نیز به عنوان گزینه جدید ارائه می کند. Adobe همچنین actionهای پشت بعضی convenience APIهای قدیمی را منتشر کرده تا توسعه دهنده بتواند آن ها را ببیند و شخصی سازی کند. این تغییر برای تیم هایی که automation پیچیده دارند فرصت کاهش endpointهای اختصاصی و تمرکز روی یک execution model است.
Contract Test و Observability را فراموش نکنید
در مهاجرت API، تست موفقیت فقط دریافت HTTP 2xx نیست. برای هر endpoint یک contract test بسازید که payload واقعی v2 را serialize کند، job را تا پایان poll کند و خروجی نهایی را از object storage بخواند. سپس propertyهای مورد نیاز محصول مانند media type، ابعاد، وجود layerها، نام فایل و status نهایی را assert کنید. اگر pipeline شما asynchronous است، timeout و retry را هم آزمایش کنید تا یک پاسخ دیرهنگام باعث duplicate job یا overwrite ناخواسته خروجی نشود.
Observability نیز باید هم زمان با client جدید منتقل شود. Dashboard جداگانه برای request rate، job completion time، خطای 4xx/5xx، timeout در status polling و خطای storage بسازید و metricها را بین v1 و v2 مقایسه کنید. این داده به شما اجازه می دهد rollout مرحله ای را بر اساس واقعیت متوقف یا ادامه دهید. بدون telemetry، تیم ممکن است فقط خطاهای گزارش شده از کاربران را ببیند و degradationهای ظریف مثل افزایش latency یا fail شدن یک نوع فایل خاص را دیر کشف کند.
استراتژی مهاجرت بدون Big Bang
- از log یا API gateway فهرست endpointهای v1 و Lightroom را که واقعاً مصرف می شوند استخراج کنید؛ به مستندات قدیمی پروژه اکتفا نکنید.
- برای هر endpoint، mapping رسمی v2 و breaking changeهای request، response، storage و status را ثبت کنید.
- client v2 را کنار client قدیمی بسازید و credential فعلی OAuth Server-to-Server را با hostname و scope درست آزمایش کنید.
- golden test fixtureهای تصویر و PSD تعریف کنید و خروجی v1/v2 را از نظر قابل مشاهده و metadataهای مورد نیاز مقایسه کنید.
- polling /v2/status/{jobId}، timeout، retry و error mapping را جداگانه تست کنید؛ job async فقط به create request محدود نیست.
- در staging ترافیک نمونه را به v2 بفرستید و latency، failure rate و اندازه output را مانیتور کنید.
- اگر امکان feature flag دارید، rollout را مرحله ای کنید و fallback را فقط تا زمانی نگه دارید که v1 واقعاً در دسترس است.
- پس از cutover، مدل های v1، allowlistهای قدیمی، secrets غیرضروری و dashboardهای legacy را حذف کنید تا بدهی migration باقی نماند.
پرسش های متداول
Photoshop API v1 چه زمانی EOL شد؟
Adobe تاریخ پایان عمر Photoshop API v1 را 31 ژوئیه 2026 اعلام کرده است.
Lightroom API هم باید به v2 مهاجرت کند؟
بله. Adobe Lightroom API را نیز در 31 ژوئیه 2026 EOL کرده و مقصد مهاجرت را Photoshop API v2 معرفی می کند.
آیا فقط Base URL را عوض کنیم کافی است؟
خیر. payload، نام فیلدها، output، status، JPEG quality، PNG compression و چند endpoint اصلی تغییر کرده اند.
آیا OAuth credentialهای قبلی عوض می شوند؟
طبق راهنمای Adobe، authentication همان OAuth Server-to-Server باقی می ماند.
مسیر جدید عملیات Lightroom چیست؟
عملیات متعددی مثل autoTone، presets و XMP در v2 زیر /v2/edit یکپارچه شده اند.
Depth Blur در v2 وجود دارد؟
Behavior Catalog فعلی Adobe می گوید Depth Blur قدیمی هنوز در v2 پشتیبانی نمی شود.
منابع رسمی و جمع بندی
تاریخ EOL Photoshop در اعلامیه رسمی پایان عمر Photoshop API v1 و وضعیت Lightroom در اعلامیه رسمی پایان عمر Lightroom API آمده است. تغییرات معماری و breaking changeها را راهنمای رسمی مهاجرت v1 به v2 توضیح می دهد و جزئیات endpoint به endpoint در Behavior Catalog رسمی v2 قابل بررسی است.
جمع بندی: اگر هنوز v1 یا Lightroom API را دارید، موضوع دیگر planning آینده نیست؛ deadline گذشته است. migration امن با inventory واقعی endpointها شروع می شود، سپس قرارداد v2 به صورت مستقل پیاده می شود و با fixtureهای واقعی تصویر و سند تست می گردد. بزرگ ترین اشتباه، تغییر hostname و فرض سازگاری payload است. v2 فرصت ساده کردن pipeline را دارد، اما باید breaking changeها و استثناهایی مثل Depth Blur را آگاهانه مدیریت کنید.
