اجرای نمونه کد

جستجوگر APIهای گوگل به صورت پویا نمونه‌های کد تولید می‌کند. این نمونه‌های کد طوری طراحی شده‌اند که بتوان آنها را کپی و به صورت محلی اجرا کرد. برای مشاهده نمونه‌ها، در پنل کناری جستجوگر APIها، روی گزینه «تمام صفحه» (Full screen کلیک کنید. شکل زیر، جستجوگر APIهای تمام صفحه توسعه‌یافته را نشان می‌دهد:

پنل تمام صفحه API Explorer برای API کتاب‌های گوگل
شکل 2 : پنل تمام صفحه APIs Explorer برای API کتاب‌های گوگل.

به طور پیش‌فرض، API Explorer نحوه استفاده از cURL برای اجرای درخواست شما را نشان می‌دهد. برخی از APIها ممکن است نمونه‌هایی را برای زبان‌های دیگر مانند جاوا اسکریپت، جاوا و پایتون نیز نشان دهند.

اجرای نمونه‌های کد به صورت محلی

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

اعتبارنامه‌ها بسته به نوع داده (عمومی یا خصوصی) که متد به آن دسترسی دارد، یکی از موارد زیر هستند:

  • برای داده‌های عمومی، اعتبارنامه یک کلید API است.

  • برای داده‌های خصوصی، اعتبارنامه یا یک فایل client_secret.json حاوی شناسه کلاینت OAuth 2.0 و رمز کلاینت شما یا یک توکن دسترسی OAuth 2.0 است.

حلقه

تنظیم کنید

  1. برای ایجاد یا انتخاب یک پروژه برای برنامه خود و فعال کردن API، دستورالعمل‌های موجود در مستندات API را دنبال کنید.
  2. در کنسول ابری، یک کلید API ایجاد کنید.
  3. در کنسول ابری، یک اعتبارنامه‌ی OAuth client ID برای یک برنامه‌ی وب ایجاد کنید و https://developers.google.com/oauthplayground به عنوان URL تغییر مسیر استفاده کنید.
  4. در محیط OAuth 2.0 Playground ، پیکربندی OAuth 2.0 کلیک کنید.
  5. گزینه «از اعتبارنامه‌های خودتان استفاده کنید» را تیک بزنید.
  6. شناسه کلاینت و رمز کلاینت تولید شده در مرحله ۳ را وارد کنید.
  7. در فیلد scopes، محدوده‌ای که می‌خواهید با متد شما استفاده شود را تایپ کنید و روی Authorize APIs کلیک کنید.
  8. (اختیاری) اگر صفحه ورود به سیستم نمایش داده شد، حسابی را که می‌خواهید استفاده کنید انتخاب کنید.
  9. (اختیاری) اگر صفحه مجوز نمایش داده شد، روی «پذیرش» کلیک کنید.
  10. برای توکن‌ها روی کد مجوز اکسچنج کلیک کنید. یک توکن برگردانده می‌شود.
  11. در نمونه کد cURL، عبارت [YOUR_API_KEY] را با کلید API تولید شده در مرحله 2 جایگزین کنید: 'https://www.googleapis.com/drive/v3/files?key= [YOUR_API_KEY] ' \
  12. در نمونه کد cURL، [YOUR_ACCESS_TOKEN] را با توکن دسترسی تولید شده در مرحله 10 جایگزین کنید: --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN] ' \

اجرای نمونه کد

از خط فرمان، دستور cURL را اجرا کنید. دستور باید مشابه این باشد:

curl \
'https://www.googleapis.com/drive/v3/files?key=AIzaSyBiKcaoXmVApwnT24hitQG_dwjGvAj6Ddw' \
--header 'Authorization: Bearer ya29.a0ARrdaM_yQn9MWBpJgKPx880BSnRYIizRYIDz0JN9e66nSliIYpqNXmPsvv2ccfplCTG_U4b1' \
--header 'Accept: application/json' \
--compressed

جاوا اسکریپت

تنظیم کنید

  1. برای ایجاد یا انتخاب یک پروژه برای برنامه خود و فعال کردن API، دستورالعمل‌های موجود در مستندات API را دنبال کنید.
  2. در کنسول ابری، یک کلید API ایجاد کنید.
  3. در کنسول ابری، یک اعتبارنامه شناسه کلاینت OAuth برای یک «برنامه وب» ایجاد کنید و مبدأهای مجاز جاوا اسکریپت را برای شناسایی URL که از آن درخواست‌ها را ارسال خواهید کرد، مانند http://localhost ، تنظیم کنید.
  4. نمونه کد کامل را در یک فایل محلی که برای وب سرور شما قابل دسترسی است، مانند /var/www/html/example.html ، کپی کنید.

  5. خطی را در نمونه کد که کلید API یا شناسه کلاینت را تنظیم می‌کند، پیدا کنید و مقدار آن را با مقادیر تولید شده در مرحله ۲ و ۳ جایگزین کنید:

    • کلید API: gapi.client.setApiKey( YOUR_API_KEY );
    • شناسه کلاینت OAuth 2.0: gapi.client.init({ 'clientId': ' YOUR_CLIENT_ID ',

اجرای نمونه کد

  1. فایل را در مرورگر خود، مانند http://localhost/example.html ، باز کنید. توصیه می‌کنیم از مرورگری با کنسول اشکال‌زدایی مانند گوگل کروم استفاده کنید.
  2. (اختیاری) اگر صفحه ورود به سیستم نمایش داده شد، حسابی را که می‌خواهید استفاده کنید انتخاب کنید.
  3. (اختیاری) اگر صفحه مجوز نمایش داده شد، روی پذیرش کلیک کنید. کنسول اشکال‌زدایی باید پاسخ متد را به عنوان یک شیء JSON نمایش دهد.

جاوا

پیش‌نیازها

  • جاوا ۱.۷ یا بالاتر.
  • معدل ۷ یا بالاتر.

تنظیم کنید

  1. برای ایجاد یا انتخاب یک پروژه برای برنامه خود و فعال کردن API، دستورالعمل‌های موجود در مستندات API را دنبال کنید.
  2. بسته به نوع داده‌ای که متد به آن دسترسی دارد، یک کلید API (داده‌های عمومی) یا یک شناسه کلاینت OAuth 2.0 (داده‌های خصوصی) ایجاد کنید.
  3. نوع برنامه را روی برنامه دسکتاپ تنظیم کنید.
  4. اگر یک شناسه کلاینت OAuth 2.0 ایجاد کرده‌اید، فایل JSON حاوی اطلاعات احراز هویت OAuth 2.0 خود را دانلود کنید. نام این فایل چیزی شبیه به client_secret_ CLIENTID .json است که در آن CLIENTID شناسه کلاینت پروژه شماست.

  5. در دایرکتوری کاری خود، دستورات زیر را برای ایجاد ساختار پروژه جدید اجرا کنید:

    $ gradle init --type basic
$ mkdir -p src/main/java src/main/resources

  6. اگر در مرحله ۲ یک شناسه کلاینت OAuth 2.0 ایجاد کرده‌اید، نام فایل JSON که دانلود کرده‌اید را به client_secret.json تغییر دهید.

  7. فایل تغییر نام داده شده را در دایرکتوری src/main/resources که در مرحله ۵ ایجاد کردید، ذخیره کنید.

  8. در دایرکتوری کاری خود، فایل build.gradle را باز کنید و محتویات آن را با موارد زیر جایگزین کنید:

    apply plugin: 'java'
apply plugin: 'application'

mainClassName = 'ApiExample'
sourceCompatibility = 1.7
targetCompatibility = 1.7
version = '1.0'

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.google.api-client:google-api-client:1.23.0'
    compile 'com.google.oauth-client:google-oauth-client-jetty:1.23.0'
    API_SPECIFIC_DEPENDENCY
}

  9. در فایل build.gradle ، خطی که می‌گوید API_SPECIFIC_DEPENDENCY با دستورالعملی برای کامپایل کد مربوط به API که فراخوانی می‌کنید، جایگزین کنید. در اینجا نمونه‌ای از API YouTube Analytics آورده شده است:

    compile 'com.google.apis:google-api-services-youtubeAnalytics:v2-rev16-1.23.0'

    دستورالعمل از این الگو پیروی می‌کند:

    compile 'com.google.apis:google-api-services-API_NAME:API_VERSION-   revREVISION-CL_VERSION'

کجا:

  • API_NAME نام API فهرست‌شده در گیت‌هاب برای API است. برای یافتن نام، روی لینک نسخه در کنار API خود در صفحه Supported Google APIs کلیک کنید. لینک نسخه به گیت‌هاب هدایت می‌شود. نام API در قسمت بالای صفحه و وسط آن قرار دارد و قبل از آن googleapis/google-apis-services- آمده است. به عنوان مثال، برای نسخه ۳ API درایو، API_NAME drive است.
  • API_VERSION نسخه API فهرست شده برای API است که در زیر نام API در صفحه APIهای پشتیبانی شده گوگل ذکر شده است.
  • REVISION شماره‌ی ویرایش ذکر شده در مرجع JavaDoc برای API است. مرجع JavaDoc را می‌توانید در https://googleapis.dev/java/google-api-services- API_NAME /latest/index.html بیابید.
  • CL_VERSION نسخه کتابخانه کلاینت است. این مقدار همچنین در مرجع JavaDoc ظاهر می‌شود.
  • از دایرکتوری کاری خود، نمونه کد را از APIs Explorer به src/main/java/ApiExample.java کپی کنید. (نام کلاس در هر نمونه ApiExample است، بنابراین نیازی به تغییر فایل build.gradle برای اجرای نمونه‌های مختلف ندارید.)

اجرای نمونه کد

برای اجرای مثال از دستور زیر استفاده کنید:

  gradle -q run

این نمونه باید درخواست API شما را اجرا کند و پاسخ را در STDOUT چاپ کند. همچنین می‌توانید سرویسی را که فراخوانی می‌کنید بررسی کنید تا اثرات درخواست‌هایی که داده‌ها را می‌نویسند را ببینید.

نود جی اس

پیش‌نیازها

  • نود جی اس

  • کتابخانه کلاینت APIهای گوگل برای Node.js:

    • اگر قبلاً کتابخانه کلاینت را نصب نکرده‌اید، دستور زیر را اجرا کنید: 
    npm install googleapis --save
    • اگر قبلاً کتابخانه کلاینت را نصب کرده‌اید، توصیه می‌کنیم آن را به‌روزرسانی کنید تا مطمئن شوید که به‌روزترین کلاس‌ها را برای کتابخانه‌ای که آزمایش می‌کنید، دارید. برای به‌روزرسانی کتابخانه کلاینت، دستور زیر را اجرا کنید: 
    npm update googleapis --save

تنظیم کنید

  1. برای ایجاد یا انتخاب یک پروژه برای برنامه خود و فعال کردن API، دستورالعمل‌های موجود در مستندات API را دنبال کنید.
  2. بسته به نوع داده‌ای که متد به آن دسترسی دارد، یک کلید API (داده‌های عمومی) یا یک شناسه کلاینت OAuth 2.0 (داده‌های خصوصی) ایجاد کنید.
  3. نوع برنامه را روی برنامه دسکتاپ تنظیم کنید.
  4. اگر یک شناسه کلاینت OAuth 2.0 ایجاد کرده‌اید، فایل JSON حاوی اطلاعات احراز هویت OAuth 2.0 خود را دانلود کنید. نام این فایل چیزی شبیه به client_secret_ CLIENTID .json است که در آن CLIENTID شناسه کلاینت پروژه شماست.
  5. نمونه کد را در یک فایل محلی کپی کنید و نمونه را طوری تغییر دهید که کلید API یا فایل اسرار کلاینت شما را به درستی شناسایی کند. در این نمونه، مقدار کلید API برابر با YOUR_API_KEY و محل فایل اسرار کلاینت YOUR_CLIENT_SECRET_FILE.json است.

اجرای نمونه کد

برای اجرای مثال از دستور زیر استفاده کنید:

  node sample.js

اکثر نمونه‌ها یک پاسخ API (یا چیز دیگری) را به STDOUT چاپ می‌کنند.

پی اچ پی

پیش‌نیازها

  • PHP 5.4 یا بالاتر با رابط خط فرمان (CLI) و افزونه JSON.
  • ابزار مدیریت وابستگی Composer که به صورت سراسری نصب شده است.

  • کتابخانه کلاینت APIهای گوگل برای PHP:

    • اگر قبلاً کتابخانه کلاینت را نصب نکرده‌اید، دستور زیر را اجرا کنید: 

      composer require google/apiclient:^2.0

    • اگر قبلاً کتابخانه کلاینت را نصب کرده‌اید، توصیه می‌کنیم آن را به‌روزرسانی کنید تا مطمئن شوید که به‌روزترین کلاس‌ها را برای کتابخانه‌ای که آزمایش می‌کنید، دارید. برای به‌روزرسانی کتابخانه کلاینت، دستور زیر را اجرا کنید: 

      composer update google/apiclient --with-dependencies

اجرای نمونه کد

برای اجرای مثال از دستور زیر استفاده کنید: 

  php sample.php

اکثر نمونه‌ها یک پاسخ API (یا چیز دیگری) را به STDOUT چاپ می‌کنند.

پایتون

پیش‌نیازها

  • پایتون ۲.۷ یا پایتون ۳.۵+
  • ابزار مدیریت بسته pip

  • کتابخانه کلاینت APIهای گوگل برای پایتون: 

    pip install --upgrade google-api-python-client

  • کتابخانه‌های google-auth-oauthlib و google-auth-httplib2 برای احراز هویت کاربر: 

    pip install --upgrade google-auth-oauthlib google-auth-httplib2

تنظیم کنید

  1. برای ایجاد یا انتخاب یک پروژه برای برنامه خود و فعال کردن API، دستورالعمل‌های موجود در مستندات API را دنبال کنید.
  2. بسته به نوع داده‌ای که متد به آن دسترسی دارد، یک کلید API (داده‌های عمومی) یا یک شناسه کلاینت OAuth 2.0 (داده‌های خصوصی) ایجاد کنید.
  3. نوع برنامه را روی برنامه دسکتاپ تنظیم کنید.
  4. اگر یک شناسه کلاینت OAuth 2.0 ایجاد کرده‌اید، فایل JSON حاوی اطلاعات احراز هویت OAuth 2.0 خود را دانلود کنید. نام این فایل چیزی شبیه به client_secret_ CLIENTID .json است که در آن CLIENTID شناسه کلاینت پروژه شماست.
  5. نمونه کد را در یک فایل محلی کپی کنید و نمونه را طوری تغییر دهید که کلید API یا فایل اسرار کلاینت شما را به درستی شناسایی کند. در این نمونه، مقدار کلید API برابر با YOUR_API_KEY و محل فایل اسرار کلاینت YOUR_CLIENT_SECRET_FILE.json است.

اجرای نمونه کد

برای اجرای مثال از دستور زیر استفاده کنید: 

  python sample.py

اکثر نمونه‌ها یک پاسخ API (یا چیز دیگری) را به STDOUT چاپ می‌کنند.

روبی

پیش‌نیازها

  • روبی ۲.۰ یا بالاتر

  • کتابخانه کلاینت APIهای گوگل برای روبی: 

    gem install google-api-client`

تنظیم کنید

  1. برای ایجاد یا انتخاب یک پروژه برای برنامه خود و فعال کردن API، دستورالعمل‌های موجود در مستندات API را دنبال کنید.
  2. بسته به نوع داده‌ای که متد به آن دسترسی دارد، یک کلید API (داده‌های عمومی) یا یک شناسه کلاینت OAuth 2.0 (داده‌های خصوصی) ایجاد کنید.
  3. نوع برنامه را روی برنامه دسکتاپ تنظیم کنید.
  4. اگر یک شناسه کلاینت OAuth 2.0 ایجاد کرده‌اید، فایل JSON حاوی اطلاعات احراز هویت OAuth 2.0 خود را دانلود کنید. نام این فایل چیزی شبیه به client_secret_ CLIENTID .json است که در آن CLIENTID شناسه کلاینت پروژه شماست.
  5. نمونه کد را در یک فایل محلی کپی کنید و نمونه را طوری تغییر دهید که کلید API یا فایل اسرار کلاینت شما را به درستی شناسایی کند. در این نمونه، مقدار کلید API برابر با YOUR_API_KEY و محل فایل اسرار کلاینت YOUR_CLIENT_SECRET_FILE.json است.

اجرای نمونه کد

برای اجرای مثال از دستور زیر استفاده کنید: 

  ruby sample.rb

اکثر نمونه‌ها یک پاسخ API (یا چیز دیگری) را به STDOUT چاپ می‌کنند.

رفع مشکلات نمونه

گفتگوی مجوز ظاهر نمی‌شود

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

اگر در صفحه مجوز روی «مجاز» کلیک کردید و هیچ اتفاقی نیفتاد، تنظیمات پنجره‌های بازشو مرورگر خود را تغییر دهید تا پنجره‌های بازشو فعال شوند.

خطای ۴۰۱ یا ۴۰۳ دریافت کردم

اگر هنگام آزمایش یک نمونه با خطای ۴۰۱ یا ۴۰۳ مواجه شدید، احتمالاً به دلیل مشکل در یکی از موارد زیر است:

  • API برای پروژه شما فعال نیست. دستورالعمل‌های API خود را در مورد نحوه ایجاد یک پروژه و فعال کردن API بررسی کنید.
  • شما از نوع مجوز اشتباه (کلید API به جای OAuth 2.0) استفاده می‌کنید.
  • شما از OAuth 2.0 استفاده می‌کنید، اما با دامنه‌ی بسیار محدود.
  • وقتی کلید API خود را تنظیم می‌کنید، محدودیت‌هایی را برای جلوگیری از استفاده غیرمجاز از اعتبارنامه‌های خود تنظیم می‌کنید. با این حال، درخواست این محدودیت‌ها را برآورده نمی‌کند. برای اطلاعات بیشتر، به «استفاده از محدودیت‌های کلید API» مراجعه کنید.

اخطاری در مورد محتوای ترکیبی دریافت کردم

اگر از نقاط پایانی گوگل کلود استفاده می‌کنید و نقطه پایانی خود را در یک سرور توسعه اجرا می‌کنید، ممکن است مرورگر شما هشداری در مورد محتوای ترکیبی (mixed content) بدهد. این هشدار به این دلیل رخ می‌دهد که API Explorer از طریق HTTPS بارگذاری می‌شود، اما وقتی API شما به صورت محلی اجرا می‌شود، روی HTTP میزبانی می‌شود.

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

path/to/chrome --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:port

برای مثال: 

/usr/bin/google-chrome-stable --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:8080

شما فقط باید این هشدار را برای اهداف آزمایشی محلی پنهان کنید.

فقط جاوا اسکریپت: gapi تعریف نشده است

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