راه اندازی اولیه

برای ادامه، مطمئن شوید که مراحل پیش‌نیازها را تکمیل کرده‌اید و ما پروژه شما را برای دسترسی به APIهای پروفایل تجاری تأیید کرده‌ایم.

فعال کردن APIها

هفت API مرتبط با پروفایل تجاری وجود دارد که باید در کنسول Google Cloud فعال شوند:

  • رابط برنامه‌نویسی کاربردی (API) گوگل برای کسب‌وکار من
  • رابط برنامه‌نویسی کاربردی (API) مدیریت حساب کاربری کسب و کار من
  • API اقامتگاه کسب و کار من
  • API اقدامات مکان کسب و کار من
  • رابط برنامه‌نویسی کاربردی اعلان‌های کسب‌وکار من
  • API تأیید هویت کسب و کار من
  • API اطلاعات کسب و کار من

فعال کردن یک API

اگر تمام پیش‌نیازها را تکمیل کرده‌اید و به API دسترسی پیدا کرده‌اید، اما هنوز نمی‌توانید از میانبر ارائه شده استفاده کنید، می‌توانید API را با مراحل زیر به صورت دستی فعال کنید.

برای فعال کردن API برای پروژه خود، مراحل زیر را انجام دهید:

  1. کتابخانه API را در کنسول API گوگل باز کنید . در صورت درخواست، یک پروژه را انتخاب کنید یا یک پروژه جدید ایجاد کنید. کتابخانه API تمام API های موجود را که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند، فهرست می کند.
  2. اگر API مورد نظر برای فعال‌سازی در لیست قابل مشاهده نیست، از جستجو برای یافتن آن استفاده کنید.
  3. API مورد نظر خود را انتخاب کنید و سپس روی دکمه‌ی فعال‌سازی کلیک کنید.
  4. در صورت درخواست، صورتحساب را فعال کنید.
  5. در صورت درخواست، شرایط خدمات API را بپذیرید.

اگر کاربر فضای کاری گوگل هستید، تأیید کنید که نمایه تجاری گوگل (Google Business Profile) برای حساب شما در سازمان فضای کاری گوگل فعال باشد . اگر نمایه تجاری گوگل (Google Business Profile) برای حساب شما در سازمان فضای کاری گوگل غیرفعال باشد، هنگام استفاده از APIهای GBP با خطای «403 - PERMISSION DENIED» مواجه خواهید شد.

درخواست شناسه کلاینت OAuth 2.0

از آنجا که برنامه شما به داده‌های محافظت‌شده و غیرعمومی دسترسی دارد، به یک شناسه کلاینت OAuth 2.0 نیاز دارید. این به برنامه شما اجازه می‌دهد تا از طرف کاربران برنامه، درخواست مجوز برای دسترسی به داده‌های موقعیت مکانی سازمان شما را داشته باشد.

برنامه شما باید یک توکن OAuth 2.0 را به همراه هرگونه درخواست API پروفایل تجاری که به داده‌های خصوصی کاربر دسترسی دارد، ارسال کند.

اگر قبلاً این کار را نکرده‌اید، به بخش «اعتبارنامه‌ها» در کنسول Google Cloud بروید و برای ایجاد اعتبارنامه‌های OAuth 2.0 خود، روی «ایجاد اعتبارنامه‌ها» > «شناسه کلاینت OAuth» کلیک کنید. پس از ایجاد اعتبارنامه‌ها، می‌توانید شناسه کلاینت خود را در صفحه «اعتبارنامه‌ها» مشاهده کنید. برای جزئیاتی مانند رمز کلاینت، آدرس‌های تغییر مسیر، آدرس مبدأ جاوا اسکریپت و آدرس ایمیل، روی شناسه کلاینت کلیک کنید.

اصول اولیه REST را بیاموزید

دو روش برای فراخوانی APIها وجود دارد:

اگر تصمیم دارید از کتابخانه‌های کلاینت استفاده نکنید، باید اصول اولیه REST را درک کنید.

REST سبکی از معماری نرم‌افزار است که رویکردی مناسب و سازگار برای درخواست و تغییر داده‌ها ارائه می‌دهد.

اصطلاح REST مخفف عبارت " REST " (Representational State Transfer) است. در زمینه APIهای گوگل، به استفاده از افعال HTTP برای بازیابی و تغییر نمایش داده‌های ذخیره شده توسط گوگل اشاره دارد.

یک سیستم RESTful منابع را در یک مخزن داده ذخیره می‌کند. یک کلاینت درخواستی را برای سرور ارسال می‌کند تا یک عمل خاص مانند ایجاد، بازیابی، به‌روزرسانی یا حذف یک منبع را انجام دهد و سرور این عمل را انجام داده و پاسخی را ارسال می‌کند. این پاسخ اغلب به شکل نمایشی از منبع مشخص شده است.

در APIهای RESTful گوگل، کلاینت یک عمل را با یک فعل HTTP مانند GET ، POST ، PUT یا DELETE مشخص می‌کند. کلاینت یک منبع را با یک شناسه منبع یکنواخت (URI) منحصر به فرد جهانی به شکل زیر مشخص می‌کند:

https://apiName.googleapis.com/apiVersion/resourcePath?parameters

از آنجا که تمام منابع API دارای URI های منحصر به فرد با قابلیت دسترسی HTTP هستند، REST امکان ذخیره سازی داده ها را فراهم می کند و برای کار با زیرساخت توزیع شده وب بهینه شده است.

ممکن است تعاریف متد موجود در مستندات استانداردهای HTTP 1.1 برای شما مفید باشد. این تعاریف شامل مشخصات GET ، POST ، PUT و DELETE هستند.

REST در APIهای پروفایل تجاری

عملیات APIهای پروفایل تجاری مستقیماً به افعال REST HTTP نگاشت می‌شوند.

قالب خاص APIهای پروفایل تجاری در URI زیر نشان داده شده است:

https://apiName.googleapis.com/apiVersion/resourcePath?parameters

مجموعه کامل URI های مورد استفاده برای هر عملیات پشتیبانی شده در API ها در مستندات مرجع API های پروفایل تجاری آمده است.

مسیرهای منابع بر اساس نقطه پایانی متفاوت هستند.

برای مثال، مسیر منبع به یک حساب کاربری مانند مثال زیر نمایش داده می‌شود:

accounts/accountId

مسیر منبع برای یک مکان به شکل زیر نمایش داده می‌شود:

locations/locationId

اصول اولیه JSON را بیاموزید

APIهای پروفایل تجاری، داده‌ها را با فرمت JSON برمی‌گردانند.

نشانه‌گذاری شیء جاوا اسکریپت ( JSON ) یک قالب داده رایج و مستقل از زبان است که نمایش متنی از ساختارهای داده دلخواه را ارائه می‌دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.

استفاده از OAuth 2.0 Playground برای ایجاد درخواست HTTP

شما می‌توانید از OAuth 2.0 Playground برای آزمایش APIهای پروفایل تجاری استفاده کنید. از آنجا که APIهای پروفایل تجاری APIهای عمومی نیستند، برای استفاده از آنها در Playground باید چند مرحله اضافی انجام دهید. برای ادامه کار یک برنامه وب به یک شناسه کلاینت نیاز دارید.

  1. به کنسول API گوگل بروید و پروژه خود را باز کنید. اگر شناسه کلاینت OAuth برای برنامه‌های وب ندارید، اکنون یکی ایجاد کنید:
    1. از فهرست کشویی «ایجاد اعتبارنامه‌ها» ، شناسه کلاینت OAuth را انتخاب کنید.
    2. برای نوع برنامه ، روی برنامه وب کلیک کنید.

    3. موارد زیر را به عنوان یک URI ریدایرکت معتبر اضافه کنید:

       https://developers.google.com/oauthplayground
    4. روی ایجاد کلیک کنید.
  2. شناسه کلاینت را در کلیپ‌بورد کپی کنید.
  3. به OAuth 2.0 Playground بروید.
  4. برای باز کردن گزینه‌های پیکربندی، روی نماد چرخ‌دنده کلیک کنید و تغییرات زیر را اعمال کنید:
    1. جریان OAuth را روی سمت کلاینت تنظیم کنید.
    2. استفاده از اعتبارنامه‌های OAuth خودتان را انتخاب کنید.
    3. شناسه کلاینت OAuth خود را وارد کنید.
  5. گزینه‌های پیکربندی را ببندید.

  6. در قسمت «مرحله ۱ - انتخاب و تأیید APIها»، محدوده زیر را برای APIهای نمایه کسب‌وکار در فیلد «ورود محدوده‌های خودتان» وارد کنید:

    https://www.googleapis.com/auth/business.manage
  7. روی تأیید APIها کلیک کنید.
  8. وقتی از شما خواسته شد، روی پذیرش کلیک کنید.

  9. در قسمت «مرحله ۲ - پیکربندی درخواست به API»، آدرس اینترنتی زیر را در فیلد درخواست آدرس اینترنتی (Request URI) وارد کنید:

    https://mybusinessaccountmanagement.googleapis.com/v1/accounts
  10. روی ارسال درخواست کلیک کنید. پاسخ باید وضعیت 200 OK را نشان دهد.

برای اطلاعات بیشتر در مورد نحوه‌ی ایجاد انواع مختلف درخواست‌ها، به مرجع APIهای پروفایل تجاری مراجعه کنید.

کتابخانه‌های کلاینت

کتابخانه‌های کلاینت APIهای پروفایل تجاری از قابلیت‌های APIهای پروفایل تجاری پشتیبانی می‌کنند. آن‌ها قابلیت‌های مشترکی را برای همه APIهای گوگل، مانند انتقال HTTP، مدیریت خطا، احراز هویت و تجزیه JSON، ارائه می‌دهند.

برای دانلود کتابخانه‌های کلاینت، به بخش کتابخانه‌ها مراجعه کنید.