این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

API های شخص ثالث

یکی از ویژگی‌های قدرتمند اسکریپت‌های گوگل ادز، قابلیت ادغام با داده‌ها و سرویس‌های APIهای شخص ثالث است.

این راهنما مفاهیم زیر را پوشش می‌دهد که می‌تواند به شما در نوشتن اسکریپت‌هایی برای اتصال به سایر سرویس‌ها کمک کند:

ایجاد درخواست‌های HTTP : نحوه استفاده از UrlFetchApp برای دسترسی به APIهای خارجی.
احراز هویت : ما برخی از سناریوهای رایج احراز هویت را پوشش می‌دهیم.
تجزیه پاسخ‌ها : نحوه پردازش داده‌های JSON و XML برگشتی.

ما همچنین نمونه‌هایی از تعدادی از APIهای محبوب را که این مفاهیم را نشان می‌دهند، گنجانده‌ایم.

واکشی داده‌ها با UrlFetchApp

UrlFetchApp قابلیت‌های اصلی مورد نیاز برای تعامل با APIهای شخص ثالث را فراهم می‌کند.

مثال زیر دریافت داده‌های آب و هوا از OpenWeatherMap را نشان می‌دهد. ما OpenWeatherMap را به دلیل طرح مجوزدهی و API نسبتاً ساده‌اش انتخاب کردیم.

درخواستی بدهید

مستندات OpenWeatherMap قالب درخواست آب و هوای فعلی را به شرح زیر مشخص می‌کند:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

این URL اولین مثال ما از احراز هویت را ارائه می‌دهد: پارامتر apikey الزامی است و مقدار آن برای هر کاربر منحصر به فرد است. این کلید از طریق ثبت‌نام به دست می‌آید.

پس از ثبت نام، درخواستی با استفاده از کلید می‌تواند به شرح زیر صادر شود:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

اجرای این کد منجر به نوشتن یک رشته طولانی از متن JSON در پنجره ثبت وقایع در اسکریپت‌های گوگل ادز می‌شود.

مرحله بعدی تبدیل این به فرمتی است که بتواند در اسکریپت شما استفاده شود.

داده‌های JSON

بسیاری از APIها پاسخ‌ها را در قالب JSON ارائه می‌دهند. این نشان‌دهنده‌ی سریال‌سازی اشیاء جاوااسکریپت است، به طوری که اشیاء، آرایه‌ها و انواع پایه می‌توانند به صورت رشته نمایش داده شده و منتقل شوند.

برای تبدیل یک رشته JSON - مانند رشته‌ای که از OpenWeatherMap برگردانده می‌شود - به یک شیء جاوا اسکریپت، از متد داخلی JSON.parse استفاده کنید. در ادامه مثال قبل:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

متد JSON.parse رشته را به یک شیء تبدیل می‌کند که دارای یک ویژگی به name است.

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

مدیریت خطا

مدیریت خطا هنگام کار با API های شخص ثالث در اسکریپت های شما یک نکته مهم است زیرا API های شخص ثالث اغلب به طور مکرر تغییر می کنند و مقادیر پاسخ غیرمنتظره ای ایجاد می کنند، به عنوان مثال:

URL یا پارامترهای API می‌توانند بدون اطلاع شما تغییر کنند.
کلید API شما (یا سایر اطلاعات کاربری) می‌تواند منقضی شود.
قالب پاسخ می‌تواند بدون اطلاع قبلی تغییر کند.

کدهای وضعیت HTTP

با توجه به احتمال پاسخ‌های غیرمنتظره، باید کد وضعیت HTTP را بررسی کنید. به طور پیش‌فرض، UrlFetchApp در صورت مواجهه با کد خطای HTTP، یک استثنا ایجاد می‌کند. برای تغییر این رفتار، لازم است یک پارامتر اختیاری مانند مثال زیر ارسال کنید:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

ساختار پاسخ

وقتی APIهای شخص ثالث تغییر می‌کنند، ممکن است بلافاصله از تغییراتی که ممکن است روی اسکریپت‌های شما تأثیر بگذارند، آگاه نشوید. برای مثال، اگر ویژگی name که در مثال OpenWeatherMap برگردانده شده است به locationName تغییر کند، اسکریپت‌هایی که از این ویژگی استفاده می‌کنند، با شکست مواجه می‌شوند.

به همین دلیل، بررسی اینکه آیا ساختار برگشتی مطابق انتظار است یا خیر، می‌تواند مفید باشد، برای مثال:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

داده‌ها را با UrlFetchApp پست کنید

مثال مقدماتی با OpenWeatherMap فقط داده‌ها را واکشی می‌کرد. معمولاً، فراخوانی‌های API که وضعیت را در سرور راه دور تغییر نمی‌دهند، از متد HTTP GET استفاده می‌کنند.

متد GET متد پیش‌فرض برای UrlFetchApp است. با این حال، برخی از فراخوانی‌های API، مانند فراخوانی‌های سرویسی که پیامک ارسال می‌کند، به متدهای دیگری مانند POST یا PUT نیاز دارند.

برای نشان دادن نحوه‌ی استفاده از فراخوانی‌های POST با UrlFetchApp ، مثال زیر ادغام با Slack ، یک برنامه‌ی پیام‌رسان مشارکتی، برای ارسال پیام Slack به کاربران و گروه‌های Slack را نشان می‌دهد.

اسلک را راه‌اندازی کنید

این راهنما فرض می‌کند که شما قبلاً در Slack حساب کاربری ایجاد کرده‌اید .

همانند OpenWeatherMap در مثال قبلی، برای فعال کردن ارسال پیام، دریافت یک توکن ضروری است. Slack یک URL منحصر به فرد ارائه می‌دهد تا به شما امکان ارسال پیام به تیمتان را بدهد که به آن Incoming Webhook می‌گویند.

با کلیک روی «افزودن یکپارچه‌سازی وب‌هوک‌های ورودی» و دنبال کردن دستورالعمل‌ها، یک وب‌هوک ورودی راه‌اندازی کنید . این فرآیند باید یک URL برای استفاده در پیام‌رسانی صادر کند.

ارسال درخواست POST

پس از تنظیم وب‌هوک ورودی، ارسال یک درخواست POST نیاز به استفاده از برخی ویژگی‌های اضافی در پارامتر options ارسالی به UrlFetchApp.fetch دارد:

method : همانطور که گفته شد، این مقدار پیش‌فرض GET است، اما در اینجا آن را بازنویسی کرده و روی POST تنظیم می‌کنیم.
payload : این داده‌ای است که قرار است به عنوان بخشی از درخواست POST به سرور ارسال شود. در این مثال، Slack انتظار دارد یک شیء به فرمت JSON سریال‌سازی شده باشد، همانطور که در مستندات Slack توضیح داده شده است. برای این منظور، از متد JSON.stringify استفاده می‌شود و Content-Type روی application/json تنظیم می‌شود.
```
  // Change the URL for the one issued to you from 'Setting up Slack'.
  const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
  const slackMessage = {
    text: 'Hello, slack!'
  };

  const options = {
    method: 'POST',
    contentType: 'application/json',
    payload: JSON.stringify(slackMessage)
  };
  UrlFetchApp.fetch(SLACK_URL, options);
```

مثال Slack توسعه‌یافته

مثال قبلی حداقل کد مورد نیاز برای فعال کردن پیام‌های دریافتی در Slack را نشان می‌دهد. یک نمونه‌ی توسعه‌یافته، ایجاد و ارسال گزارش عملکرد کمپین به یک گروه و همچنین برخی از گزینه‌های قالب‌بندی و نمایش را نشان می‌دهد.

پیام دریافتی

برای جزئیات بیشتر در مورد پیام‌های Slack، به بخش قالب‌بندی پیام در مستندات Slack مراجعه کنید.

داده‌های فرم

مثال قبلی استفاده از یک رشته JSON به عنوان ویژگی payload برای درخواست POST را نشان داد.

بسته به قالب payload ، UrlFetchApp رویکردهای متفاوتی برای ساخت درخواست POST در پیش می‌گیرد:

وقتی payload یک رشته باشد، آرگومان رشته‌ای به عنوان بدنه درخواست ارسال می‌شود.
وقتی payload یک شیء است، مثلاً یک نقشه از مقادیر:
```
{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
```
جفت‌های کلید-مقدار به داده‌های فرم تبدیل می‌شوند:
```
subject=Test&to=mail@example.com&body=Hello,+World!
```
همچنین هدر Content-Type برای درخواست روی application/x-www-form-urlencoded تنظیم شده است.

برخی از APIها هنگام ارسال درخواست‌های POST نیاز به استفاده از داده‌های فرم دارند، بنابراین این تبدیل خودکار از اشیاء جاوا اسکریپت به داده‌های فرم باید در نظر گرفته شود.

احراز هویت پایه HTTP

احراز هویت پایه HTTP یکی از ساده‌ترین اشکال احراز هویت است و توسط بسیاری از APIها استفاده می‌شود.

احراز هویت با اتصال نام کاربری و رمز عبور رمزگذاری شده به هدرهای HTTP در هر درخواست انجام می‌شود.

احراز هویت پایه HTTP

ساخت یک درخواست

برای ایجاد یک درخواست احراز هویت شده، مراحل زیر لازم است:

با اتصال نام کاربری و رمز عبور با استفاده از علامت دونقطه، عبارت عبور را تشکیل دهید، برای مثال username:password .
عبارت عبور با Base64 کدگذاری می‌شود، برای مثال username:password به dXNlcm5hbWU6cGFzc3dvcmQ= تبدیل می‌شود.
یک هدر Authorization به درخواست، به شکل Authorization: Basic <encoded passphrase> پیوست کنید.

قطعه کد زیر نحوه دستیابی به این هدف را در اسکریپت‌های گوگل ادز نشان می‌دهد:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

نمونه‌های احراز هویت پایه

بخش نمونه‌های کد شامل دو نمونه است که نحوه‌ی استفاده از احراز هویت پایه HTTP را نشان می‌دهد:

پلیوو

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

در Plivo ثبت نام کنید.
اسکریپت نمونه را در یک اسکریپت جدید در گوگل ادز جایگذاری کنید.
مقادیر PLIVO_ACCOUNT_AUTHID و PLIVO_ACCOUNT_AUTHTOKEN را با مقادیر موجود در داشبورد مدیریت جایگزین کنید.
آدرس ایمیل خود را همانطور که در اسکریپت مشخص شده است برای اطلاع رسانی خطاها وارد کنید.
برای استفاده از Plivo، باید شماره‌ها را خریداری کنید یا شماره‌ها را به حساب آزمایشی اضافه کنید. شماره‌های Sandbox را که می‌توانند با حساب آزمایشی استفاده شوند، اضافه کنید .
هم شماره‌ای که به عنوان فرستنده نمایش داده می‌شود و هم شماره گیرنده را اضافه کنید.
PLIVO_SRC_PHONE_NUMBER در اسکریپت به یکی از شماره‌های ثبت‌شده در سندباکس به‌روزرسانی کنید. این باید شامل کد بین‌المللی کشور باشد، برای مثال 447777123456 برای شماره بریتانیا.

توییلیو

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

در Twillio ثبت نام کنید.
اسکریپت نمونه را در یک اسکریپت جدید در گوگل ادز جایگذاری کنید.
مقادیر TWILIO_ACCOUNT_SID و TWILIO_ACCOUNT_AUTHTOKEN را با مقادیر نمایش داده شده در صفحه کنسول حساب جایگزین کنید.
TWILIO_SRC_PHONE_NUMBER با شماره موجود در داشبورد جایگزین کنید -- این شماره‌ای است که Twilio برای ارسال پیام مجاز می‌داند.

اواوت ۱.۰

بسیاری از سرویس‌های محبوب از OAuth برای احراز هویت استفاده می‌کنند. OAuth در نسخه‌ها و مدل‌های مختلفی ارائه می‌شود.

در حالی که با احراز هویت پایه HTTP ، کاربر فقط یک نام کاربری و رمز عبور دارد، OAuth به برنامه‌های شخص ثالث اجازه می‌دهد تا با استفاده از اعتبارنامه‌های مخصوص آن برنامه شخص ثالث، به حساب و داده‌های کاربر دسترسی پیدا کنند. علاوه بر این، میزان دسترسی نیز مختص آن برنامه خواهد بود.

برای پیش‌زمینه در مورد OAuth 1.0، به راهنمای OAuth Core مراجعه کنید. به طور خاص، به بخش ۶. احراز هویت با OAuth مراجعه کنید. در OAuth 1.0 سه‌پایه کامل، فرآیند به شرح زیر است:

برنامه ("مصرف‌کننده") یک توکن درخواست (request token) دریافت می‌کند.
کاربر توکن درخواست را تأیید می‌کند.
برنامه، توکن درخواست (request token) را با یک توکن دسترسی (access token) تعویض می‌کند.
برای تمام درخواست‌های منابع بعدی ، توکن دسترسی در یک درخواست امضا شده استفاده می‌شود.

برای اینکه سرویس‌های شخص ثالث بتوانند بدون تعامل با کاربر از OAuth 1.0 استفاده کنند (مثلاً همانطور که اسکریپت‌های Google Ads نیاز دارند)، مراحل ۱، ۲ و ۳ امکان‌پذیر نیست. بنابراین، برخی سرویس‌ها یک توکن دسترسی از کنسول پیکربندی خود صادر می‌کنند که به برنامه اجازه می‌دهد مستقیماً به مرحله ۴ برود. این به عنوان OAuth 1.0 تک‌پا شناخته می‌شود.

OAuth1

OAuth 1.0 در اسکریپت‌های گوگل ادز

برای اسکریپت‌های گوگل ادز، هر اسکریپت معمولاً به عنوان یک برنامه تفسیر می‌شود. از طریق کنسول یا صفحه تنظیمات مدیریت برای سرویس، معمولاً لازم است:

پیکربندی برنامه را برای نمایش اسکریپت تنظیم کنید.
مشخص کنید چه مجوزهایی به اسکریپت اضافه می‌شود.
کلید مصرف‌کننده، رمز مصرف‌کننده، توکن دسترسی و رمز دسترسی را برای استفاده با OAuth تک‌پا دریافت کنید.

اواوت ۲.۰

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

لازم نیست اطلاعات حساب کاربری خود را با برنامه به اشتراک بگذارد.
می‌تواند کنترل کند که کدام برنامه‌ها به صورت جداگانه و تا چه حد به داده‌ها دسترسی داشته باشند. (برای مثال، دسترسی اعطا شده ممکن است فقط خواندنی یا فقط به زیرمجموعه‌ای از داده‌ها باشد.)

برای استفاده از سرویس‌های دارای قابلیت OAuth 2.0 در اسکریپت‌های گوگل ادز، چندین مرحله وجود دارد:

خارج از فیلمنامه شما

به اسکریپت‌های گوگل ادز اجازه دسترسی به داده‌های کاربری خود را از طریق API شخص ثالث بدهید . در بیشتر موارد، این شامل تنظیم یک برنامه در کنسول سرویس شخص ثالث می‌شود. این برنامه نمایانگر اسکریپت شماست.

شما مشخص می‌کنید که چه حقوق دسترسی باید به برنامه اسکریپت‌های گوگل ادز داده شود و معمولاً یک شناسه کلاینت به آن اختصاص داده می‌شود. این به شما اجازه می‌دهد تا از طریق OAuth 2.0 کنترل کنید که کدام برنامه‌ها به داده‌های شما در سرویس شخص ثالث دسترسی دارند و همچنین کدام جنبه‌های آن داده‌ها را می‌توانند ببینند یا تغییر دهند.

در فیلمنامه شما

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

درخواست‌های API را انجام دهید . توکن دسترسی را با هر درخواست ارسال کنید.

جریان‌های مجوزدهی

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

ارائه‌دهندگان API تصمیم می‌گیرند که کدام نوع کمک‌هزینه را بپذیرند و این موضوع، نحوه‌ی ادغام API توسط کاربر را هدایت خواهد کرد.

پیاده‌سازی

برای تمام جریان‌های مختلف OAuth، هدف به دست آوردن یک توکن دسترسی است که می‌تواند در ادامه‌ی جلسه برای تأیید اعتبار درخواست‌ها مورد استفاده قرار گیرد.

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

الگوی کلی استفاده به این صورت است:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

اعطای اعتبارنامه مشتری

اعطای اعتبارنامه‌ی کلاینت یکی از ساده‌ترین اشکال جریان OAuth2 است که در آن برنامه در ازای صدور یک توکن دسترسی با محدودیت زمانی، یک شناسه و رمز منحصر به فرد برای برنامه مبادله می‌کند.

اعتبارنامه مشتری

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

تازه کردن اعطای توکن

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

توکن تازه‌سازی

دریافت توکن به‌روزرسانی

تفاوت اعطای توکن به‌روزرسانی این است که در حالی که جزئیات مورد نیاز برای اعطای اعتبارنامه‌های کلاینت از پیکربندی برنامه (به عنوان مثال، در پنل کنترل سرویس) می‌آید، توکن به‌روزرسانی به عنوان بخشی از یک جریان پیچیده‌تر، مانند اعطای کد مجوز ، اعطا می‌شود که نیاز به تعامل کاربر دارد:

کد مجوز

استفاده از OAuth Playground برای دریافت توکن رفرش

محیط OAuth2 رابط کاربری‌ای ارائه می‌دهد که به کاربر اجازه می‌دهد تا با طی کردن مراحل اعطای کد مجوز، توکن به‌روزرسانی (refresh token) را دریافت کند.

دکمه تنظیمات در بالا سمت راست به شما امکان می‌دهد تمام پارامترهای مورد استفاده در جریان OAuth را تعریف کنید، از جمله:

نقطه پایانی مجوز : به عنوان شروع جریان مجوز استفاده می‌شود.
نقطه پایانی توکن : به همراه توکن به‌روزرسانی برای دریافت توکن دسترسی استفاده می‌شود.
شناسه و رمز کلاینت : اطلاعات احراز هویت برای برنامه.

زمین بازی OAuth

استفاده از توکن را تازه کنید

پس از انجام مجوز اولیه، سرویس‌ها می‌توانند یک توکن به‌روزرسانی (refresh token) صادر کنند که می‌توان از آن به روشی مشابه جریان اعتبارسنجی کلاینت استفاده کرد:

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

مثال تبلیغات جستجو ۳۶۰

Search Ads 360 نمونه‌ای از یک API است که می‌تواند با یک توکن refresh استفاده شود. در این نمونه، یک اسکریپت گزارشی را تولید و برمی‌گرداند . برای جزئیات کامل سایر اقداماتی که می‌توان انجام داد، به مرجع Search Ads 360 API مراجعه کنید.

اسکریپت را ایجاد کنید

یک پروژه جدید در کنسول API ایجاد کنید و با دنبال کردن مراحل موجود در راهنمای Search Ads 360 ، یک شناسه کلاینت، رمز کلاینت و توکن به‌روزرسانی دریافت کنید و مطمئن شوید که API Search Ads 360 را فعال کرده‌اید.
اسکریپت نمونه را در یک اسکریپت جدید در گوگل ادز جایگذاری کنید.
کتابخانه نمونه OAuth2 را در زیر فهرست کدها قرار دهید.
اسکریپت را اصلاح کنید تا شامل مقادیر صحیح برای شناسه کلاینت، رمز کلاینت و توکن رفرش باشد.

مثال API اجرای اسکریپت برنامه‌ها

این مثال اجرای یک تابع در Apps Script را با استفاده از API اجرای Apps Script نشان می‌دهد. این به شما امکان می‌دهد Apps Script را از اسکریپت‌های Google Ads فراخوانی کنید.

یک اسکریپت Apps Script ایجاد کنید

یک اسکریپت جدید ایجاد کنید . نمونه زیر 10 فایل از Drive را فهرست می‌کند:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}

پیکربندی اسکریپت برنامه‌ها برای اجرا

اسکریپت را ذخیره کنید.
روی منابع > پروژه پلتفرم ابری کلیک کنید.
برای رفتن به کنسول API، روی نام پروژه کلیک کنید.
به APIها و سرویس‌ها بروید.
APIهای مناسب، در این مورد Drive API و Apps Script Execution API را فعال کنید.
اعتبارنامه‌های OAuth را از آیتم Credentials در منو ایجاد کنید.
به اسکریپت خود برگردید و از مسیر Publish > Deploy as API Executable آن را برای اجرا منتشر کنید.

اسکریپت گوگل ادز را ایجاد کنید

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

حساب‌های خدماتی

یک جایگزین برای انواع اعطایی، مفهوم حساب‌های سرویس است.

حساب‌های سرویس با انواع اعطایی متفاوت هستند، زیرا برای دسترسی به داده‌های کاربر استفاده نمی‌شوند: پس از احراز هویت، درخواست‌ها توسط حساب سرویس از طرف برنامه انجام می‌شود، نه به عنوان کاربری که ممکن است مالک پروژه باشد. به عنوان مثال، اگر حساب سرویس از Drive API برای ایجاد یک فایل استفاده کند، این فایل متعلق به حساب سرویس خواهد بود و به طور پیش‌فرض برای مالک پروژه قابل دسترسی نخواهد بود.

مثالی از API زبان طبیعی گوگل

رابط برنامه‌نویسی کاربردی زبان طبیعی، تحلیل احساسات و تحلیل موجودیت را برای متن ارائه می‌دهد.

این مثال محاسبه‌ی احساسات نسبت به متن تبلیغ - شامل عنوان یا توضیحات - را نشان می‌دهد. این مثال معیاری برای میزان مثبت بودن پیام و بزرگی آن ارائه می‌دهد: کدام بهتر است، ما کیک می‌فروشیم یا ما بهترین کیک‌های لندن را می‌فروشیم. همین امروز بخرید!؟

اسکریپت را تنظیم کنید

ایجاد یک پروژه جدید در کنسول API
فعال کردن API زبان طبیعی
فعال کردن صورتحساب برای پروژه.
یک حساب کاربری سرویس ایجاد کنید . فایل JSON مربوط به اعتبارنامه‌ها را دانلود کنید.
اسکریپت نمونه را در یک اسکریپت جدید در گوگل ادز جایگذاری کنید.
علاوه بر این، کتابخانه نمونه OAuth2 را در زیر فهرست کدها قرار دهید.
مقادیر لازم را جایگزین کنید:
- serviceAccount : آدرس ایمیل حساب سرویس، برای مثال xxxxx@yyyy.iam.gserviceaccount.com .
- key : کلید فایل JSON که هنگام ایجاد حساب سرویس دانلود شده است. -----BEGIN PRIVATE KEY... شروع می‌شود و با ...END PRIVATE KEY-----\n پایان می‌یابد.

پاسخ‌های API

APIها می‌توانند داده‌ها را در قالب‌های مختلفی برگردانند. قابل توجه‌ترین آنها XML و JSON هستند.

جی‌سون

کار با JSON به عنوان فرمت پاسخ معمولاً ساده‌تر از XML است. با این حال، هنوز هم ممکن است مشکلاتی پیش بیاید.

اعتبارسنجی پاسخ

پس از دریافت پاسخ موفقیت‌آمیز از فراخوانی API، مرحله‌ی بعدی معمولاً استفاده از JSON.parse برای تبدیل رشته‌ی JSON به یک شیء جاوا اسکریپت است. در این مرحله، منطقی است که حالتی را که تجزیه با شکست مواجه می‌شود، مدیریت کنیم:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

همچنین، اگر API تحت کنترل شما نیست، در نظر داشته باشید که ساختار پاسخ ممکن است تغییر کند و ویژگی‌ها دیگر وجود نداشته باشند:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

اعتبارسنجی

XML هنوز هم یک فرمت محبوب برای ساخت APIها است. پاسخ یک فراخوانی API را می‌توان با استفاده از متد parse در XmlService تجزیه کرد:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

اگرچه XmlService.parse خطاهای موجود در XML را تشخیص داده و بر اساس آن استثنائات را ارسال می‌کند، اما امکان اعتبارسنجی XML در برابر یک طرحواره را فراهم نمی‌کند.

عنصر ریشه

با توجه به تجزیه موفقیت‌آمیز سند XML، عنصر ریشه با استفاده از متد getRootElement() بدست می‌آید:

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

فضاهای نام

در مثال زیر، از API مربوط به Sportradar برای دریافت نتایج فوتبال برای مسابقات انتخاب شده استفاده می‌شود. پاسخ XML به شکل زیر است:

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

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

ویژگی فضای نام را از سند استخراج کنید.
هنگام پیمایش و دسترسی به عناصر فرزند از این فضای نام استفاده کنید.

نمونه زیر نحوه دسترسی به عنصر <matches> را در قطعه کد بالا نشان می‌دهد:

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

بدست آوردن مقادیر

با توجه به نمونه‌ای از برنامه فوتبال:

<match status="..." category="..." ... >
  ...
</match>

ویژگی‌ها را می‌توان بازیابی کرد، برای مثال:

const status = matchElement.getAttribute('status').getValue();

متن موجود در یک عنصر را می‌توان با استفاده از getText() خواند، اما در مواردی که چندین فرزند متنی از یک عنصر وجود داشته باشد، این متن‌ها به هم متصل می‌شوند. در مواردی که احتمال وجود چندین فرزند متنی وجود دارد، استفاده از getChildren() و تکرار روی هر فرزند را در نظر بگیرید.

مثال اسپورت رادار

این مثال کامل Sportradar، بازیابی جزئیات مسابقات فوتبال، به ویژه مسابقات لیگ برتر انگلیس را نشان می‌دهد. API فوتبال یکی از طیف وسیعی از فیدهای ورزشی ارائه شده توسط Sportradar است.

یک حساب کاربری Sportradar ایجاد کنید

به سایت توسعه‌دهنده Sportradar بروید
برای حساب آزمایشی ثبت نام کنید.
پس از ثبت نام، وارد حساب کاربری خود شوید.
پس از ورود به سیستم، به بخش «حساب من» بروید.

Sportradar ورزش‌های مختلف را در APIهای مختلف دسته‌بندی می‌کند. برای مثال، ممکن است شما دسترسی به API فوتبال را خریداری کنید اما API تنیس را نه. هر برنامه‌ای که ایجاد می‌کنید می‌تواند ورزش‌های مختلف و کلیدهای متفاوتی داشته باشد.

در قسمت برنامه‌ها، روی ایجاد یک برنامه جدید کلیک کنید. برای برنامه یک نام و توضیح بنویسید و فیلد وب‌سایت را نادیده بگیرید.
فقط گزینه صدور کلید جدید برای Soccer Trial Europe v2 را انتخاب کنید.
روی ثبت درخواست کلیک کنید.

پس از موفقیت، این باید منجر به صفحه‌ای شود که کلید API جدید شما روی آن قرار دارد.

اسکریپت نمونه را در یک اسکریپت جدید در گوگل ادز جایگذاری کنید.
کلید API موجود در لیست را با کلید جدید صادر شده جایگزین کنید و فیلد آدرس ایمیل را ویرایش کنید.

عیب‌یابی

هنگام کار با API های شخص ثالث، خطاها می‌توانند به دلایل مختلفی رخ دهند، به عنوان مثال:

کلاینت‌ها درخواست‌هایی را به سرور ارسال می‌کنند که فرمت مورد انتظار API نیست.
مشتریانی که انتظار فرمت پاسخی متفاوت از آنچه با آن مواجه شده‌اند را دارند.
کلاینت‌هایی که از توکن‌ها یا کلیدهای نامعتبر یا مقادیری که به عنوان placeholder باقی مانده‌اند استفاده می‌کنند.
مشتریانی که به محدودیت استفاده رسیده‌اند.
کلاینت‌هایی که پارامترهای نامعتبر ارائه می‌دهند.

در تمام این موارد و موارد دیگر، اولین قدم خوب در شناسایی علت مشکل، بررسی جزئیات پاسخی است که باعث خطا شده است.

تجزیه پاسخ‌ها

به طور پیش‌فرض، هر پاسخی که خطا ( کد وضعیت ۴۰۰ یا بالاتر) را برگرداند، توسط موتور اسکریپت‌های گوگل ادز ارسال می‌شود.

برای جلوگیری از این رفتار، و برای اینکه امکان بررسی خطا و پیام خطا فراهم شود، ویژگی muteHttpExceptions مربوط به پارامترهای اختیاری را روی UrlFetchApp.fetch تنظیم کنید. برای مثال:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

کدهای وضعیت رایج

200 OK نشان دهنده موفقیت است. اگر پاسخ شامل داده‌های مورد انتظار نیست، موارد زیر را در نظر بگیرید:
- برخی از APIها امکان تعیین فیلدها و/یا قالب پاسخ مورد استفاده را فراهم می‌کنند. برای جزئیات بیشتر در این مورد، مستندات API را بررسی کنید.
- یک API ممکن است چندین منبع داشته باشد که می‌توان آنها را فراخوانی کرد. برای تعیین اینکه آیا منبع دیگری برای استفاده مناسب‌تر است یا خیر، به مستندات مراجعه کنید و ببینید آیا منبع دیگری داده‌های مورد نیاز شما را برمی‌گرداند یا خیر.
- ممکن است API از زمان نوشتن کد تغییر کرده باشد. برای روشن شدن موضوع به مستندات یا توسعه‌دهنده مراجعه کنید.
400 Bad Request معمولاً به این معنی است که چیزی در قالب‌بندی یا ساختار درخواست ارسالی به سرور صحیح نیست. درخواست را بررسی کنید و آن را با مشخصات API مقایسه کنید تا مطمئن شوید که با انتظارات مطابقت دارد. برای جزئیات بیشتر در مورد نحوه بررسی درخواست‌ها، به بخش بررسی درخواست‌ها مراجعه کنید.
401 Unauthorized معمولاً به این معنی است که API بدون ارائه یا انجام موفقیت‌آمیز مجوز فراخوانی می‌شود.
- اگر API از احراز هویت پایه استفاده می‌کند، مطمئن شوید که هدر Authorization header) ساخته و در درخواست ارائه شده است.
- اگر API از OAuth 2.0 استفاده می‌کند، مطمئن شوید که توکن دسترسی دریافت شده و به عنوان توکن Bearer ارائه می‌شود.
- برای هرگونه تغییر دیگر در مجوز، مطمئن شوید که مدارک لازم برای درخواست ارائه شده است.
403 Forbidden نشان می‌دهد که کاربر مجوز دسترسی به منبع مورد درخواست را ندارد.
- اطمینان حاصل کنید که به کاربر مجوزهای لازم اعطا شده است، به عنوان مثال، در یک درخواست مبتنی بر فایل، به کاربر دسترسی به یک فایل داده شود.
404 Not Found به این معنی است که منبع مورد نظر وجود ندارد.
- بررسی کنید که URL استفاده شده برای نقطه پایانی API صحیح باشد.
- اگر منبعی را دریافت می‌کنید، بررسی کنید که منبع مورد ارجاع وجود داشته باشد (برای مثال، آیا فایل مربوط به یک API مبتنی بر فایل وجود دارد یا خیر).

درخواست‌ها را بررسی کنید

بررسی درخواست‌ها زمانی مفید است که پاسخ‌های API نشان دهند که درخواست به درستی شکل نگرفته است، برای مثال، کد وضعیت ۴۰۰. برای کمک به بررسی درخواست‌ها، UrlFetchApp یک متد همراه با متد fetch() دارد که getRequest(url, params) نام دارد.

این متد به جای ارسال درخواست به سرور، درخواستی را که قرار بود ارسال شود، می‌سازد و سپس آن را برمی‌گرداند. این به کاربر اجازه می‌دهد تا عناصر درخواست را بررسی کند تا از صحت ظاهر آن اطمینان حاصل کند.

برای مثال، اگر داده‌های فرم در درخواست شما شامل رشته‌های زیادی باشد که به هم متصل شده‌اند، ممکن است خطا در تابعی باشد که شما برای تولید داده‌های آن فرم ایجاد کرده‌اید. در ساده‌ترین حالت:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

به شما امکان می‌دهد عناصر درخواست را بررسی کنید.

ثبت درخواست‌ها و پاسخ‌ها

برای کمک به کل فرآیند بررسی درخواست‌ها و پاسخ‌ها به یک API شخص ثالث، تابع کمکی زیر می‌تواند به عنوان جایگزینی برای UrlFetchApp.fetch() استفاده شود تا هم درخواست‌ها و هم پاسخ‌ها را ثبت کند.

تمام نمونه‌های UrlFetchApp.fetch() را در کد خود با logUrlFetch() جایگزین کنید.

تابع زیر را به انتهای اسکریپت خود اضافه کنید.

function logUrlFetch(url, opt_params) {
  const params = opt_params || {};
  params.muteHttpExceptions = true;
  const request = UrlFetchApp.getRequest(url, params);
  console.log('Request:       >>> ' + JSON.stringify(request));
  const response = UrlFetchApp.fetch(url, params);
  console.log('Response Code: <<< ' + response.getResponseCode());
  console.log('Response text: <<< ' + response.getContentText());
  if (response.getResponseCode() >= 400) {
    throw Error('Error in response: ' + response);
  }
  return response;
}

هنگام اجرای اسکریپت شما، جزئیات تمام درخواست‌ها و پاسخ‌ها در کنسول ثبت می‌شود و امکان اشکال‌زدایی آسان‌تر را فراهم می‌کند.

API های شخص ثالث با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

واکشی داده‌ها با UrlFetchApp

درخواستی بدهید

داده‌های JSON

مدیریت خطا

کدهای وضعیت HTTP

ساختار پاسخ

داده‌ها را با UrlFetchApp پست کنید

اسلک را راه‌اندازی کنید

ارسال درخواست POST

مثال Slack توسعه‌یافته

داده‌های فرم

احراز هویت پایه HTTP

ساخت یک درخواست

نمونه‌های احراز هویت پایه

پلیوو

توییلیو

اواوت ۱.۰

OAuth 1.0 در اسکریپت‌های گوگل ادز

اواوت ۲.۰

جریان‌های مجوزدهی

پیاده‌سازی

اعطای اعتبارنامه مشتری

تازه کردن اعطای توکن

دریافت توکن به‌روزرسانی

استفاده از توکن را تازه کنید

مثال تبلیغات جستجو ۳۶۰

اسکریپت را ایجاد کنید

مثال API اجرای اسکریپت برنامه‌ها

یک اسکریپت Apps Script ایجاد کنید

پیکربندی اسکریپت برنامه‌ها برای اجرا

اسکریپت گوگل ادز را ایجاد کنید

حساب‌های خدماتی

مثالی از API زبان طبیعی گوگل

اسکریپت را تنظیم کنید

پاسخ‌های API

جی‌سون

اعتبارسنجی پاسخ

XML

اعتبارسنجی

عنصر ریشه

فضاهای نام

بدست آوردن مقادیر

مثال اسپورت رادار

یک حساب کاربری Sportradar ایجاد کنید

عیب‌یابی

تجزیه پاسخ‌ها

کدهای وضعیت رایج

درخواست‌ها را بررسی کنید

ثبت درخواست‌ها و پاسخ‌ها

API های شخص ثالث