ما شما را تشویق میکنیم که از کتابخانهها و نمونههای کلاینت برای پیادهسازی خود استفاده کنید. با این حال، اگر ادغام شما با API نیازهای خاصی دارد، مانند استفاده از یک زبان پشتیبانی نشده، میتوانید درخواستهای مستقیم را همانطور که در زیر توضیح داده شده است، ارسال کنید.
سبک تماس
REST سبکی از معماری نرمافزار است که رویکردی مناسب و سازگار برای درخواست و تغییر دادهها ارائه میدهد.
اصطلاح REST مخفف عبارت « Representational State Transfer » است. در زمینه APIهای گوگل، به استفاده از افعال HTTP برای بازیابی و تغییر نمایش دادههای ذخیره شده توسط گوگل اشاره دارد.
در یک سیستم RESTful، منابع در یک مخزن داده ذخیره میشوند؛ یک کلاینت درخواستی ارسال میکند که سرور یک عمل خاص (مانند ایجاد، بازیابی، بهروزرسانی یا حذف یک منبع) را انجام دهد، و سرور عمل را انجام داده و پاسخی را ارسال میکند، که اغلب به شکل نمایشی از منبع مشخص شده است.
در APIهای RESTful گوگل، کلاینت با استفاده از یک فعل HTTP مانند POST ، GET ، PUT یا DELETE ، یک عمل را مشخص میکند. این عمل یک منبع را با یک URI منحصر به فرد جهانی به شکل زیر مشخص میکند:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
از آنجا که تمام منابع API دارای URI های منحصر به فرد با قابلیت دسترسی HTTP هستند، REST امکان ذخیره سازی داده ها را فراهم می کند و برای کار با زیرساخت توزیع شده وب بهینه شده است.
ممکن است تعاریف متد موجود در مستندات استانداردهای HTTP 1.1 را مفید بیابید؛ آنها شامل مشخصاتی برای GET ، POST ، PUT و DELETE هستند.
REST در API مدیریت AdSense
عملیات پشتیبانیشده مستقیماً به افعال REST HTTP نگاشت میشوند.
قالب خاص برای آدرسهای URL مربوط به API مدیریت ادسنس عبارتند از:
https://adsense.googleapis.com/v2/resourceID?parameters
که در آن resourceID شناسهی یک کلاینت تبلیغاتی، واحد تبلیغاتی، کانال url، کانال سفارشی یا مجموعهی گزارشها است و parameters هر پارامتری است که برای پرسوجو اعمال میشود.
قالب پسوندهای مسیر resourceID به شما امکان میدهد منبعی را که در حال حاضر روی آن کار میکنید، شناسایی کنید، برای مثال:
https://adsense.googleapis.com/v2/accounts/account_id/adclients https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels ...
مجموعه کامل URI های مورد استفاده برای هر عملیات پشتیبانی شده در API در سند مرجع API مدیریت AdSense خلاصه شده است.
در اینجا چند مثال از نحوه عملکرد این مورد در API مدیریت AdSense آورده شده است.
لیست مشتریان تبلیغات:
GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/فهرست واحدهای تبلیغاتی در کلاینت تبلیغات ca-pub-1234567890123456:
GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits
قالب داده
JSON (نمادگذاری شیء جاوا اسکریپت) یک قالب داده رایج و مستقل از زبان است که نمایش متنی سادهای از ساختارهای داده دلخواه را ارائه میدهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.
تأیید درخواستها
توجه داشته باشید که AdSense از حسابهای سرویس پشتیبانی نمیکند، در عوض باید از جریان برنامه نصبشده استفاده کنید.
هر درخواستی که برنامه شما به API مدیریت AdSense ارسال میکند، باید شامل یک توکن مجوز باشد. این توکن همچنین برنامه شما را به گوگل معرفی میکند.
درباره پروتکلهای مجوزدهی
برنامه شما باید از OAuth 2.0 برای تأیید درخواستها استفاده کند. هیچ پروتکل تأیید دیگری پشتیبانی نمیشود. اگر برنامه شما از ورود با گوگل استفاده میکند، برخی از جنبههای تأیید برای شما انجام میشود.
تأیید درخواستها با OAuth 2.0
تمام درخواستها به API مدیریت AdSense باید توسط یک کاربر احراز هویت شده تأیید شوند.
این فرآیند با شناسه کلاینت OAuth تسهیل میشود.
دریافت شناسه کلاینت OAuthیا یکی را در صفحه اعتبارنامهها ایجاد کنید.
جزئیات فرآیند مجوزدهی یا «جریان» برای OAuth 2.0 بسته به نوع برنامهای که مینویسید تا حدودی متفاوت است. فرآیند کلی زیر برای همه انواع برنامه اعمال میشود:
- وقتی برنامه شما نیاز به دسترسی به دادههای کاربر دارد، از گوگل درخواست محدوده خاصی از دسترسی را میکند.
- گوگل یک صفحه رضایتنامه به کاربر نمایش میدهد و از او میخواهد که به برنامه شما اجازه دهد تا برخی از دادههایش را درخواست کند.
- اگر کاربر تأیید کند، گوگل یک توکن دسترسی کوتاهمدت به برنامه شما میدهد.
- برنامه شما دادههای کاربر را درخواست میکند و توکن دسترسی را به درخواست پیوست میکند.
- اگر گوگل تشخیص دهد که درخواست شما و توکن معتبر هستند، دادههای درخواستی را برمیگرداند.
برخی از جریانها شامل مراحل اضافی مانند استفاده از توکنهای تازهسازی برای به دست آوردن توکنهای دسترسی جدید هستند. برای اطلاعات دقیق در مورد جریانها برای انواع مختلف برنامهها، به مستندات OAuth 2.0 گوگل مراجعه کنید.
اطلاعات مربوط به محدوده OAuth 2.0 برای API مدیریت AdSense در اینجا آمده است:
| دامنه | معنی |
|---|---|
https://www.googleapis.com/auth/adsense | دسترسی خواندن/نوشتن به دادههای AdSense. |
https://www.googleapis.com/auth/adsense.readonly | دسترسی فقط خواندنی به دادههای AdSense. |
برای درخواست دسترسی با استفاده از OAuth 2.0، برنامه شما به اطلاعات دامنه و همچنین اطلاعاتی که گوگل هنگام ثبت برنامه شما ارائه میدهد (مانند شناسه کلاینت و رمز کلاینت) نیاز دارد.
نکته: کتابخانههای کلاینت APIهای گوگل میتوانند بخشی از فرآیند مجوزدهی را برای شما انجام دهند. این کتابخانهها برای زبانهای برنامهنویسی مختلفی در دسترس هستند؛ برای جزئیات بیشتر ، صفحه مربوط به کتابخانهها و نمونهها را بررسی کنید.
درخواست کردن
مرحله آخر، ارسال درخواست API است. برای اطلاعات بیشتر به مستندات مرجع مراجعه کنید.