API های شخص ثالث

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

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

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

واکشی داده ها با 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 می شود که در پنجره ورود به اسکریپت های Google Ads نوشته می شود.

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

داده های 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 را بررسی کنید. به‌طور پیش‌فرض، در صورت مواجهه با کد خطای HTTP، UrlFetchApp یک استثنا ایجاد می‌کند. برای تغییر این رفتار، لازم است یک پارامتر اختیاری مانند مثال زیر ارسال کنید:

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');
}

POST داده ها با UrlFetchApp

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

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

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

Slack را راه اندازی کنید

این راهنما فرض می کند که قبلاً برای یک حساب Slack ثبت نام کرده اید.

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

با کلیک بر روی Add Incoming Webhooks Integration و دنبال کردن دستورالعمل ها ، یک Webhook ورودی راه اندازی کنید . فرآیند باید یک URL برای استفاده برای پیام‌رسانی صادر کند.

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

پس از راه اندازی Webhook ورودی خود، ایجاد یک درخواست 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);

مثال Extended 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

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

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

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

قطعه زیر نحوه دستیابی به این هدف را در Google Ads Scripts نشان می دهد:

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);

پلیوو

Plivo سرویسی است که ارسال و دریافت پیامک ها را از طریق API آنها تسهیل می کند. این نمونه ارسال پیام را نشان می دهد.

  1. با Plivo ثبت نام کنید.
  2. اسکریپت نمونه را در یک اسکریپت جدید در Google Ads جای‌گذاری کنید.
  3. مقادیر PLIVO_ACCOUNT_AUTHID و PLIVO_ACCOUNT_AUTHTOKEN را با مقادیر داشبورد مدیریت جایگزین کنید.
  4. آدرس ایمیل خود را همانطور که در اسکریپت مشخص شده برای اطلاع از خطاها وارد کنید.
  5. برای استفاده از Plivo، یا باید شماره ها را خریداری کنید یا شماره هایی را به حساب آزمایشی اضافه کنید. شماره‌های جعبه ایمنی را که می‌توان با حساب آزمایشی استفاده کرد، اضافه کنید .
  6. هم شماره ای را که به عنوان فرستنده ظاهر می شود و هم شماره گیرنده را اضافه کنید.
  7. PLIVO_SRC_PHONE_NUMBER در اسکریپت را به یکی از شماره‌های جعبه ایمنی که به تازگی ثبت‌شده است، به‌روزرسانی کنید. این باید شامل کد بین‌المللی کشور باشد، برای مثال 447777123456 برای یک شماره بریتانیا.

تویلیو

Twilio سرویس دیگری است که ارسال و دریافت پیامک ها را از طریق API آنها تسهیل می کند. این نمونه ارسال پیام را نشان می دهد.

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

OAuth 1.0

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

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

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

  1. برنامه ("مصرف کننده") یک نشانه درخواست دریافت می کند.
  2. کاربر رمز درخواست را مجاز می کند.
  3. برنامه توکن درخواست را با یک نشانه دسترسی مبادله می کند.
  4. برای تمام درخواست‌های منابع بعدی ، رمز دسترسی در یک درخواست امضا شده استفاده می‌شود.

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

OAuth1

OAuth 1.0 در اسکریپت های Google Ads

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

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

OAuth 2.0

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

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

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

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

به Google Ads Scripts مجوز اعطا کنید تا از طریق API شخص ثالث به داده‌های کاربر شما دسترسی داشته باشد . در بیشتر موارد این شامل راه اندازی یک برنامه در کنسول سرویس شخص ثالث است. این برنامه نشان دهنده اسکریپت تبلیغات گوگل شما است.

شما مشخص می‌کنید که کدام حقوق دسترسی به برنامه Google Ads Script باید داده شود و معمولاً یک شناسه مشتری به آن اختصاص داده می‌شود. این به شما امکان می‌دهد از طریق OAuth 2 کنترل کنید کدام برنامه‌ها به داده‌های شما در سرویس شخص ثالث دسترسی دارند، و همچنین، چه جنبه‌هایی از آن داده‌ها را می‌توانند ببینند یا تغییر دهند.

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

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

درخواست های 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 یک رابط کاربری فراهم می‌کند که به کاربر اجازه می‌دهد تا از طریق اعطای کد مجوز برای دریافت نشانه‌ی تازه‌سازی قدم بگذارد.

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

  • نقطه پایان مجوز : به عنوان شروع جریان برای مجوز استفاده می شود.
  • نقطه پایانی رمز : با نشانه رفرش برای به دست آوردن نشانه دسترسی استفاده می شود.
  • شناسه مشتری و راز : اعتبار برنامه.

زمین بازی OAuth

استفاده از یک اسکریپت برای به دست آوردن یک نشانه رفرش

یک جایگزین مبتنی بر اسکریپت برای تکمیل جریان در نمونه تولید توکن به‌روزرسانی موجود است.

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

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

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

به عنوان مثال Search Ads 360

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

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

مثال Apps Script Execution API

این مثال اجرای یک تابع در Apps Script با استفاده از Apps Script Execution API را نشان می دهد. این اجازه می دهد تا 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;
}
Apps Script را برای اجرا پیکربندی کنید
  1. اسکریپت را ذخیره کنید.
  2. روی منابع > پروژه پلتفرم ابری کلیک کنید.
  3. روی نام پروژه کلیک کنید تا به کنسول API بروید.
  4. به APIs & Services بروید.
  5. APIهای مناسب، در این مورد Drive API و Apps Script Execution API را فعال کنید.
  6. اعتبارنامه OAuth را از آیتم Credentials در منو ایجاد کنید.
  7. در اسکریپت خود، اسکریپت را برای اجرا از Publish > Deploy as API Executable منتشر کنید.
اسکریپت Google Ads را ایجاد کنید
  1. اسکریپت نمونه را در یک اسکریپت جدید در Google Ads جای‌گذاری کنید.
  2. علاوه بر این، نمونه کتابخانه OAuth2 را در زیر فهرست کد قرار دهید.
  3. اسکریپت را به گونه ای اصلاح کنید که حاوی مقادیر صحیح برای شناسه مشتری، رمز سرویس گیرنده و نشانه تازه سازی باشد.

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

یک جایگزین برای انواع کمک هزینه فوق، مفهوم حساب های خدماتی است.

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

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

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

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

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

پاسخ های API

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

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();

فضاهای نام

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

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

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

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

نمونه زیر نحوه دسترسی به عنصر <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

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

یک حساب Sportradar راه اندازی کنید
  1. به سایت توسعه دهنده Sportradar بروید
  2. برای یک حساب آزمایشی ثبت نام کنید.
  3. پس از ثبت نام، وارد حساب کاربری خود شوید.
  4. پس از ورود به سیستم، به MyAccount بروید.

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

  1. در زیر برنامه ها روی ایجاد یک برنامه جدید کلیک کنید. به برنامه یک نام و توضیحات بدهید و قسمت وب سایت را نادیده بگیرید.
  2. فقط گزینه Issue a new key را برای Soccer Trial Europe v2 انتخاب کنید.
  3. روی ثبت برنامه کلیک کنید.

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

  1. اسکریپت نمونه را در یک اسکریپت جدید در Google Ads جای‌گذاری کنید.
  2. کلید API را در لیست با کلید بدست آمده در بالا جایگزین کنید و فیلد آدرس ایمیل را ویرایش کنید.

عیب یابی

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

  • کلاینت هایی که درخواست هایی را به سرور در قالبی صادر می کنند که توسط API انتظار نمی رود.
  • مشتریانی که انتظار فرمت پاسخ متفاوتی با فرمت قبلی دارند.
  • مشتریانی که از نشانه‌ها یا کلیدهای نامعتبر یا مقادیر باقی‌مانده به‌عنوان مکان‌نما استفاده می‌کنند.
  • مشتریانی که محدودیت های استفاده را اعمال می کنند.
  • مشتریانی که پارامترهای نامعتبر را ارائه می کنند.

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

پاسخ ها را تجزیه کنید

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

برای جلوگیری از این رفتار، و اجازه بررسی خطا و پیام خطا، ویژگی 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 در درخواست ساخته و ارائه شده است.
    • اگر API از OAuth 2.0 استفاده می کند، مطمئن شوید که نشانه دسترسی به دست آمده است و به عنوان یک توکن حامل عرضه می شود.
    • برای هر گونه تغییر دیگر در مجوز، مطمئن شوید که اعتبارنامه لازم برای درخواست ارائه شده است.

  • 403 Forbidden نشان می دهد که کاربر مجوز منبع درخواست شده را ندارد.

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

  • 404 Not Found یعنی منبع درخواستی وجود ندارد.

    • بررسی کنید که URL استفاده شده برای نقطه پایانی API درست باشد.
    • اگر منبعی را واکشی می کنید، بررسی کنید که منبعی که به آن ارجاع داده می شود وجود دارد (به عنوان مثال، اگر فایل برای یک API مبتنی بر فایل وجود دارد).

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

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

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

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

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

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

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

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

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

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

    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;
}

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