این بخش به پرسشهای متداول درباره «ثبتنام توسعهدهنده» برای Merchant API میپردازد.
ثبتنام عمومی
پرسشهای متداول درباره روند ثبتنام:
آیا ثبتنام توسعهدهنده برای استفاده از Merchant API الزامی است؟
بله. باید اطلاعات تماس توسعهدهنده خود را ثبت کنید تا Google بتواند بهروزرسانیهای مهم مختص API، مانند اعلامیههای خدمات و اطلاعات ویژگیهای جدید را ارسال کند.
اگر فقط میخواهید Merchant API را کاوش و آزمایش کنید، میتوانید از ابزارهایی مثل Google OAuth Playground و API Explorer استفاده کنید که نیازی به ثبتنام ندارند.
چند وقت یکبار باید ثبتنام کنم؟
ثبتنام یک راهاندازی یکباره برای هر پروژه Google Cloud است. چه با چند حساب فروشنده کار کنید چه نه، عملیات ثبت را فقط یکبار انجام میدهید و این عملیات برای همه کاربران و حسابهای سرویس در پروژه Google Cloud پیوندشده اعمال میشود.
وقتی پروژه Google Cloud با موفقیت ثبت شد، پیوند فعال میماند مگراینکه با فراخوانی روش unregisterGcp صریحاً برداشته شود. نمیتوانید پروژههای همرسانیشده و متعلق به Google مثل APIs Explorer یا OAuth Playground را ثبت کنید.
کدام نشانی ایمیل را باید بهعنوان اطلاعات تماس توسعهدهنده ارائه دهم؟
توصیه میکنیم از نشانی ایمیل شرکتی فرد استفاده کنید. یا میتوانید از نامهای مستعار گروه عمومی استفاده کنید. نمیتوانید از ایمیلهای حساب سرویس استفاده کنید، زیرا ارتباطات برای گیرندگان انسانی درنظر گرفته شده است. Google بهروزرسانیهای مهم مختص API، مانند اعلامیههای خدمات و اطلاعات ویژگیهای جدید را ارسال میکند.
اگر نشانی ایمیل متعلق به کاربر فعلی در حساب Merchant Center باشد،
نقش API developer بهطور خودکار به او اعطا میشود. اگر نداشته باشد،
دعوتی به آن نشانی ارسال میشود.
فیلد نشانی ایمیل تماس توسعهدهنده در روش registerGcp اختیاری است. اگر هنگام ثبتنام مقداری برای این فیلد ارائه نکنید، باید کاربری ایجاد کنید که نقش API developer را در واسط کاربری Merchant Center یا با فراخوانی روش accounts.users.create داشته باشد.
آیا ایمیل تماس توسعهدهنده باید «حساب Google» باشد؟
بله. برای استفاده از ایمیل غیرGoogle موجود، میتوانید آن را با انتخاب گزینه استفاده از ایمیل موجود در فرایند ثبتنام ایجاد حساب Google به «حساب Google» منسوب کنید. نمیتوانید از ایمیلهای حساب سرویس استفاده کنید چون حسابهای سرویس نمیتوانند ایمیل دریافت کنند.
چگونه اصالتسنجی و صدور مجوز را برای تماس ثبتنام انجام دهم؟
دو سناریوی اصالتسنجی متمایز برای اصالتسنجی و مجوزدهی تماس ثبتنام دردسترس است که به مورد استفاده شما بستگی دارد:
- OAuth 2.0: برای ارائهدهندگان یا آژانسهای شخص ثالثی که چندین حساب فروشنده را مدیریت میکنند
- حسابهای سرویس: برای دسترسی به حساب Merchant Center خودتان
نمودار قبلی دو جریان اصالتسنجی و صدور مجوز را برای تماس ثبتنام نشان میدهد. میتوانید یکی از این گزینهها را انتخاب کنید:
- استفاده از OAuth با نشانی ایمیلی مثل account@email.com که با «حساب Google» مرتبط است
- استفاده از حساب سرویس مانند sa@project.iam.gserviceaccount.com
اگر تصمیم گرفتید از OAuth استفاده کنید:
- در پروژه Google Cloud خود، اعتبارنامههای OAuth برای ایمیلتان ایجاد کنید
- مطمئن شوید که نشانی ایمیل مجاز در Merchant Center شما وجود دارد و نوع دسترسی آن
ADMINاست
اگر تصمیم گرفتید از حساب سرویس استفاده کنید:
- مطمئن شوید که حساب خدمات در پروژه Google Cloud شما وجود دارد
- مطمئن شوید که نشانی ایمیل مرتبط با حساب سرویس در Merchant Center شما وجود دارد و نوع دسترسی آن
ADMINاست
فراخوانی ثبت را تحت زمینه امنیتی هویت اصالتسنجیکننده، بااستفاده از فراخوانیهای مستقیم API یا کتابخانههای کارخواه انجام دهید. نشانی ایمیلی برای تماس با توسعهدهنده ارائه دهید، برای مثال developer@email.com.
اگر تماس ثبتنام موفقیتآمیز باشد، کاربری با نشانی ایمیل توسعهدهنده ارائهشده و نقش API developer در Merchant Center شما وجود دارد. بهعنوان پاسخ، منبع DeveloperRegistration را دریافت میکنید.
تفاوت بین ایمیل اصالتسنجی و ایمیل تماس توسعهدهنده چیست؟
این دو نشانی ایمیل اهداف متمایزی را در بومسازگان Merchant API دنبال میکنند:
- اصالتسنجی ایمیل: معمولاً از ایمیل مرتبط با حساب Google یا حساب سرویس بهعنوان هویت برای مجاز کردن درخواستها به Merchant API استفاده میکنید، مشروط بر اینکه:
- در Merchant Center شما وجود دارد و نقش
ADMINرا دارد. - «پروژه Google Cloud» که Merchant API در آن فعال است، میزبان کارخواه OAuth یا حساب سرویس مرتبط با ایمیلی است که فراخوانیهای API را مجاز میکند.
- در Merchant Center شما وجود دارد و نقش
- ایمیل تماس توسعهدهنده: ایمیل تماس توسعهدهنده نیز باید با «حساب Google» مرتبط باشد، اما بهعنوان مخاطب اصلی برای اعلامیههای مهم سرویس و بهروزرسانیهای میانای برنامهسازی کاربردی از Google عمل میکند. این حساب میتواند متعلق به یک کاربر یا گروهی از کاربران باشد. بهطور پیشفرض، نقش
API developerرا در Merchant Center دریافت میکند.
آیا باید دعوت دریافتی ازطریق ایمیل تماس توسعهدهنده را بپذیرم؟
بله. گیرنده ایمیل تماس توسعهدهنده که ارائه میدهید ۱۴ روز فرصت دارد تا دعوت را بپذیرد. ثبتنام فقط پساز پذیرفتن دعوتنامه تکمیل میشود. بااینحال، در این مدت میتوانید فراخوانهای میانای برنامهسازی کاربردی را انجام دهید.
اگر دعوت در زمان مشخصشده پذیرفته نشود، پیوند دعوت منقضی میشود. دیگر نمیتوانید فراخوانیهای Merchant API را انجام دهید و باید فرایند ثبتنام را ازنو شروع کنید.
چرا ثبتنام توسعهدهنده من با خطای «حساب آزمایشی» ناموفق است؟
ثبتنام توسعهدهنده به حسابهای تولید (زنده) محدود شده است تا از پایداری ادغام اطمینان حاصل شود. اگر از حسابی استفاده میکنید که بهطور خاص برای آزمایش ایجاد شده است و بهعنوان «حساب آزمایشی» در Merchant Center علامتگذاری شده است، ثبتنام رد خواهد شد.
آیا میتوانم حساب فرعیای را که برای مشتری مدیریت میکنم ثبت کنم؟
اکیداً توصیه میکنیم حسابی را ثبت کنید که نشاندهنده هویت کسبوکار شما باشد. ثبت کردن حساب فرعی مشتری مجاز نیست و ممکن است با خطا مواجه شود؛ اگر آن مشتری سرویس شما را ترک کند یا حساب را حذف کند، ممکن است کل ادغام API شما غیرفعال شود.
آیا وبسایت من باید ادعا شود یا فقط درستیسنجی شود؟
برای ثبتنام توسعهدهنده، وبسایت باید تأییدشده باشد. این کار ثابت میکند که شما کنترل مدیریتی بر سایت مرتبط با حساب دارید. درحالیکه ادعای مالکیت برای ویژگیهای دیگر مثل «آگهیهای Shopping» الزامی است، درستیسنجی پیشنیاز اصلی برای ثبت API است.
مدیریت حساب و پروژه
پرسشهای متداول درباره مدیریت حساب و پروژه:
با چندین حساب Merchant Center کار میکنم. آیا باید هر «حساب Merchant Center» را که میخواهم با Merchant API استفاده کنم ثبت کنم؟
نه. اگر توسعهدهنده شخص ثالث یا نمایندگیای هستید که چندین حساب فروشنده را مدیریت میکند، پروژه Google Cloud خود را با حساب Merchant Center اصلی خودتان ثبت میکنید، نه با حساب هریک از فروشندگانتان. به این ترتیب، شما بهعنوان توسعهدهنده برای همه کارهای میانای برنامهسازی کاربردی که برای فروشندگان خود انجام میدهید، نمایندگی میکنید.
با چندین حساب Merchant Center کار میکنم. چگونه «حساب Merchant Center» اصلیام را انتخاب کنم؟
انتخاب حساب اصلی برای استفاده به نوع کسبوکارتان بستگی دارد:
- بازارگاههایی که ازقبل حساب پیشرفته دارند: اگر کسبوکارتان بهعنوان بازارگاه فعالیت میکند و ازقبل حساب پیشرفته دارد که نماینده کل پلاتفرم است، از شناسه این حساب موجود بهعنوان «حساب Merchant Center» اصلی استفاده کنید.
- سرویسهای مقایسه قیمت (CSS): اگر CSS هستید، از شناسه حساب CSS یا شناسه حساب گروه CSS منحصربهفردتان استفاده کنید.
- آژانسها، توسعهدهندگان، و دیگر اشخاص ثالث: اگر کسبوکار شخص ثالثی مانند آژانس یا توسعهدهنده شخص ثالث هستید که چندین حساب فروشنده را مدیریت میکند و شناسه Merchant Center واحدی ندارید که نماینده کسبوکارتان باشد، باید حساب Merchant Center اصلی جدیدی ایجاد کنید و درخواست کنید که به حساب پیشرفته تبدیل شود.
وقتی پروژه Google Cloud شما در حساب Merchant Center اصلیتان ثبت شد، میتوانید از همان پروژه برای مدیریت هر حساب Merchant Center دیگری که به آن دسترسی دارید استفاده کنید، بدون اینکه لازم باشد آن حسابها را بهطور جداگانه ثبت کنید.
از چند پروژه Google Cloud استفاده میکنم. آیا باید هرکدام را ثبت کنم؟
بله. ازآنجاییکه فرایند ثبت، پروژه Google Cloud فراخواننده را پیوند میدهد، باید فراخوانی registerGcp را از هر پروژه Google Cloud که برای فراخوانی میانای برنامهسازی کاربردی استفاده میکنید انجام دهید.
هر پروژه Google Cloud را در هر زمان فقط میتوان در یک حساب Merchant Center ثبت کرد. بااینحال، یک حساب Merchant Center میتواند چندین پروژه Google Cloud ثبتشده داشته باشد. بهطور مشابه، میتوانید از همان نشانی ایمیل توسعهدهنده برای انجام چندین ثبتنام در چندین پروژه Google Cloud یا چندین Merchant Center استفاده کنید.
اگر پروژه Google Cloud را با چند حساب Merchant Center ثبت کنم چه اتفاقی میافتد؟
تلاش برای ثبت پروژه Google Cloud که قبلاً با حساب Merchant Center دیگری ثبت شده است، منجر به خطای ALREADY_REGISTERED میشود.
چگونه فراخوانی API ثبتنام توسعهدهنده را اصالتسنجی کنم؟
برای اصالتسنجی کردن فراخوانی میانای برنامهسازی کاربردی ثبتنام توسعهدهنده برای Merchant API، از اطلاعات اعتباری مدیریتشده ازطریق «پروژه Google Cloud» استفاده میکنید. دو گزینه اصلی برای هویتی که اصالتسنجی را انجام میدهد دارید:
- «حساب Google» مانند Gmail بااستفاده از OAuth 2.0: این روش از اطلاعات کاربری کارخواه OAuth 2.0 که در «پروژه Google Cloud» شما تولید شده است استفاده میکند. فراخوانی میانای برنامهسازی کاربردی ازطرف «حساب Google» خاصی که کاربر به آن وارد شده است مجاز میشود.
- حساب سرویس: این روش از «حساب سرویس Google Cloud» استفاده میکند که نوع خاصی از «حساب Google» است که برای برنامهها درنظر گرفته شده است. اعتبارنامههای «حساب خدمات» نیز در پروژه Google Cloud شما مدیریت میشود.
برای ثبت موفقیتآمیز توسعهدهنده، هویت اصالتسنجیکننده («حساب Google» یا «حساب سرویس») باید معیارهای زیر را در Merchant Center برآورده کند:
- بهعنوان کاربر در Merchant Center وجود داشته باشد: نشانی ایمیل مرتبط با «حساب Google» اصالتسنجی یا «حساب سرویس» باید بهعنوان کاربر در حساب Merchant Center که ثبت میکنید اضافه شود.
- نقش سرپرست الزامی است: این کاربر باید نقش
ADMINرا در آن حساب Merchant Center خاص داشته باشد.
هنگام فراخوانی API:
- اگر از فراخوانیهای مستقیم میانای برنامهسازی کاربردی استفاده میکنید، باید «کد دسترسی» معتبری را در سرصفحه
Authorizationدریافت و ارائه کنید. این کد با جریان OAuth 2.0 برای «حساب Google» یا جریان اصالتسنجی سرور به سرور برای «حساب سرویس» تولید میشود. - کتابخانههای مشتری ارائهشده توسط Google معمولاً پیچیدگیهای دریافت و بازآوری «کدهای دسترسی» را بهعنوان بخشی از پیکربندی خود برای شما مدیریت میکنند.
کاربر اصالتسنجیکننده ممکن است همان کاربر مخاطب توسعهدهنده نباشد. برای اطلاعات بیشتر، به تفاوت بین ایمیل اصالتسنجی و ایمیل تماس توسعهدهنده چیست؟ مراجعه کنید.
هر چند وقت یکبار باید کدهای دسترسی را بازآوری کنم؟
کدهای دسترسی برای «حسابهای سرویس» و OAuth 2.0 معمولاً پساز ۱ ساعت منقضی میشوند. بااینحال، سازوکار دریافت کلید جدید به روش اصالتسنجیای که استفاده میکنید بستگی دارد:
- حسابهای سرویس از کلید خصوصی یا اعتبارنامههای محیط برای ایجاد کد دسترسی جدید درصورت نیاز استفاده میکنند.
- جریانهای OAuth 2.0 از refresh_token برای فراخوانی نقطه پایانی کد Google OAuth2 برای دریافت کد دسترسی ۱ ساعته جدید استفاده میکنند.
اکیداً توصیه میکنیم از «کتابخانههای رسمی Google Auth» استفاده کنید که این چرخش را بهطور خودکار انجام میدهند تا برنامهتان هرگز با زمان ازکارافتادگی مواجه نشود.
کاربران و نقشها
پرسشهای متداول درباره کاربران و نقشها:
آیا حساب ایمیل توسعهدهنده باید ازقبل در Merchant Center وجود داشته باشد؟
نه. اگر حساب ایمیل ثبتنام ازقبل در Merchant Center وجود نداشته باشد، Merchant API حساب را با ایمیل مشخصشده در وضعیت «درحال انتظار» در Merchant Center ایجاد میکند. اگر نشانی ایمیل توسعهدهنده
متعلق به کاربر فعلی در حساب Merchant Center باشد، بهطور خودکار
نقش API developer به او اعطا میشود.
آیا ایمیل تماس توسعهدهنده باید حقوق «سرپرست» در Merchant Center داشته باشد؟
نه. کاربر Merchant Center منسوب به ایمیل تماس توسعهدهنده
بهطور پیشفرض نقش API developer را دریافت میکند که برای دریافت
اعلانهای مهم لازم است. بااینحال، این نقش حداقل اجازهها را در Merchant Center دارد. برای اینکه این کاربر بتواند تماسهای دیگر با «میانای برنامهسازی کاربردی» برقرار کند یا تنظیمات را در واسط کاربری Merchant Center مدیریت کند، باید نقشهای دیگری مثل STANDARD یا ADMIN به او اعطا کنید. برای اطلاعات بیشتر درباره نقشهای Merchant Center، «انواع دسترسی» را ببینید.
نقش «API developer» چه اجازههایی دارد؟
نقش API developer نقشی با حداقل حقوق در Merchant Center است. اگر قصد دارید از ایمیل تماس توسعهدهنده برای مجاز کردن تماسها با Merchant API استفاده کنید، توصیه میکنیم اجازههای ADMIN یا STANDARD را اضافه کنید تا کاربر بتواند تماسهای API را انجام دهد.
آیا باید هر کاربر توسعهدهنده یا حساب سرویسی را که API را فراخوانی میکند ثبت کنم؟
نه. ثبتنام توسعهدهنده به پروژه Google Cloud مورداستفاده برای فراخوانیهای API گره خورده است، نه به کاربران یا حسابهای سرویس بهصورت مجزا. وقتی پروژه Google Cloud با موفقیت در حساب Merchant Center اصلی شما ثبت شد، میتوانید از هر هویتی که ازطریق پروژه Google Cloud پیوندشده بااستفاده از اعتبارنامههای OAuth یا حسابهای سرویس مدیریت میشود برای مجاز کردن فراخوانیهای Merchant API استفاده کنید، بهشرطی که در Merchant Center شما وجود داشته باشند و نقش ADMIN به آنها اختصاص داده شده باشد.
چگونه میتوانم ایمیل تماس توسعهدهنده را پساز ثبتنام اولیه تغییر دهم؟
برای مدیریت یا تغییر مخاطبین، از سرویس استاندارد accounts.users یا
صفحه «دسترسی و سرویسها» در میانای کاربر Merchant Center برای افزودن یا
برداشتن کاربران با نقش API developer استفاده کنید.
اگر آخرین کاربر «API developer» از حساب Merchant Center برداشته شود چه اتفاقی میافتد؟
برای جلوگیری از اختلال فوری در سرویس، مهلت ارفاقی ۳۰ روزه فعال میشود. درطول این مدت:
- سرپرستان سه ایمیل الزامی اعلامیه خدمات دریافت خواهند کرد (معمولاً حدود ۳۰، ۱۷، و ۴ روز قبلاز مسدود شدن).
- فراخوانهای میانای برنامهسازی کاربردی همچنان بهطور عادی کار خواهند کرد.
- اگر
API developerجدیدی قبلاز منقضی شدن مهلت ارفاقی اضافه نشود، فراخوانیهای میانای برنامهسازی کاربردی از پروژههای Google Cloud مرتبط با خطایAUTH_GCP_NOT_REGISTEREDمسدود خواهد شد.
وقتی مهلت ارفاقی ۳۰ روزه بهپایان میرسد، فراخوانیهای میانای برنامهسازی کاربردی از پروژههای Google Cloud مرتبط مسدود میشود و تا زمانی که اطلاعات تماس توسعهدهنده معتبر بازیابی نشود، خطای AUTH_GCP_NOT_REGISTERED دریافت میکنند.
اگر شناسه Merchant Center که ثبتنام توسعهدهنده با آن انجام شده است حذف شود چه اتفاقی میافتد؟
حساب Merchant Center مورداستفاده برای ثبتنام توسعهدهنده را درحالیکه ادغام شما فعال است حذف نکنید. حذف این حساب فوراً ادغام شما را قطع میکند و دیگر نمیتوانید از پروژه Google Cloud مرتبط، فراخوانیهای میانای برنامهسازی کاربردی را انجام دهید.
اگر باید آن حساب Merchant Center را حذف کنید، ابتدا باید روش unregisterGcp را فراخوانی کنید تا پیوند بهطور ایمن برداشته شود و فقط پساز آن برای حذف شناسه Merchant Center اقدام کنید. اگر میخواهید همچنان از Merchant API استفاده کنید، باید بلافاصله پساز لغو ثبتنام شناسه فعلی، با شناسه Merchant Center دیگری ثبتنام کنید. فقط در این صورت برای حذف شناسه Merchant Center اقدام کنید.
چرا نمیتوانم نقش «API developer» را در Merchant Center ببینم؟
نقش API developer فقط پساز انجام ثبتنام توسعهدهنده برای حساب Merchant Center مربوطه در میانای کاربری Merchant Center قابلمشاهده است. حسابهای Merchant Center بدون ثبتنام، نقش API developer را نمیبینند.
موارد استفاده ویژه
پرسشهای متداول درباره موارد استفاده خاص:
من یک کارگزاری یا توسعهدهنده طرف سوم هستم که چندین حساب فروشنده را مدیریت میکنم. بهترین روش برای راهاندازی این چیست؟
توسعهدهندگان و آژانسهای شخص ثالث باید حساب Merchant Center اصلی خود را حفظ کنند و همه پروژههای Google Cloud خود را در آن حساب واحد و متمرکز ثبت کنند. پروژه Google Cloud خود را با حساب هر فروشنده بهطور جداگانه ثبت نکنید.
ثبتنام برای Google App Scripts چگونه کار میکند؟
App Scripts معمولاً در پروژه Google Cloud پیشفرض اجرا میشود. باید این شناسه پیشفرض Google Cloud را در حساب Merchant Center خود ثبت کنید. Google Cloud ID بهطور خودکار توسط API دریافت میشود، بنابراین نیازی نیست آن را بهعنوان پارامتر ارائه دهید.
آیا میتوانم بررسی کنم که شناسه Merchant Center برای شناسه پروژه Google Cloud خاصی ثبت شده است یا نه؟
بله. بااستفاده از روش getAccountForGcpRegistration میتوانید بررسی کنید کدام شناسه Merchant Center برای پروژه Google Cloud خاصی ثبت شده است. برای برداشتن پیوند پروژه Google Cloud به حساب Merchant Center، از روش unregisterGcp استفاده کنید.
انتقال Content API به Merchant API برای برنامه Google و YouTube در کاربران Shopify
پرسشهای متداول درباره انتقال از Content API به Merchant API برای پلاتفرمها و برنامههای شخص ثالث:
آیا برای انتقال از Content API به Merchant API باید کاری انجام دهم؟
لازم نیست اقدامی انجام دهید. اگر از برنامه Google & YouTube در Shopify برای مدیریت فیدهای Merchant Center خود استفاده میکنید، انتقال از Content API به Merchant API توسط Google انجام خواهد شد.
آیا انتقال شناسههای محصول من را تغییر میدهد؟
نه، انتقال شناسههای محصول را در فیدهای Merchant Center شما تغییر نمیدهد.
آیا برای تکمیل انتقال باید برنامه Google & YouTube را در Shopify بازنصب کنم؟
برای تکمیل انتقال، لازم نیست کاری انجام دهید. لازم نیست برنامه Google و YouTube را بازنصب کنید.
چرا هنوز منابع داده Content API را در Merchant Center میبینم؟
ممکن است منابع داده Content API همچنان در Merchant Center درطول انتقال به Merchant API نمایش داده شوند. این موارد طبیعی است و نیازی به اقدام ازسوی شما ندارد.