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