ביצוע דוגמאות של קוד

הכלי Google APIs Explorer יוצר באופן דינמי דוגמאות קוד. דוגמאות הקוד האלה נועדו להעתקה ולהרצה מקומית. כדי לראות את הדוגמאות, לוחצים על סמל המסך המלא בחלונית הצדדית של הכלי APIs Explorer. באיור הבא מוצג הכלי APIs Explorer במסך מלא:

חלונית במסך מלא ב-APIs Explorer עבור Google Books API
איור 2: חלונית המסך המלא של APIs Explorer עבור Google Books API.

כברירת מחדל, ב-APIs Explorer מוצגות הוראות לשימוש ב-cURL כדי להריץ את הבקשה. יכול להיות שבחלק מממשקי ה-API יוצגו גם דוגמאות לשפות אחרות, כמו JavaScript,‏ Java ו-Python.

הרצת דוגמאות קוד באופן מקומי

בכרטיסיות הבאות מוסברים הדרישות המוקדמות והשלבים להרצת דוגמאות קוד. כדי להריץ את דוגמאות הקוד, צריך ליצור ולהשתמש באמצעי אימות משלכם. הסבר על יצירת פרויקט ואישורים מופיע במסמכי התיעוד של Google API הספציפי.

האישורים הם אחד מהסוגים הבאים, בהתאם לסוג הנתונים (ציבוריים או פרטיים) שהשיטה ניגשת אליהם:

  • לנתונים ציבוריים, אמצעי האימות הוא מפתח API.

  • לגבי נתונים פרטיים, פרטי הכניסה הם קובץ client_secret.json שמכיל את מזהה הלקוח ואת הסוד של הלקוח ב-OAuth 2.0, או אסימון גישה ב-OAuth 2.0.

cURL

תהליך ההגדרה

  1. פועלים לפי ההוראות בתיעוד של ה-API כדי ליצור פרויקט לאפליקציה או לבחור פרויקט קיים ולהפעיל את ה-API.
  2. יוצרים מפתח API במסוף Cloud.
  3. במסוף Cloud, יוצרים פרטי כניסה של מזהה לקוח OAuth לאפליקציית אינטרנט ומשתמשים ב-https://developers.google.com/oauthplayground ככתובת ה-URI להפניה אוטומטית.
  4. ב-OAuth 2.0 Playground, לוחצים על OAuth 2.0 Configuration (הגדרת OAuth 2.0) .
  5. מסמנים את התיבה Use your own credentials (שימוש בפרטי הכניסה שלך).
  6. מזינים את מזהה הלקוח ואת סוד הלקוח שנוצרו בשלב 3.
  7. בשדה 'היקפים', מקלידים את ההיקף שרוצים להשתמש בו עם ה-method ולוחצים על Authorize APIs (מתן הרשאה לממשקי API).
  8. (אופציונלי) אם מוצג מסך כניסה, בוחרים את החשבון שבו רוצים להשתמש.
  9. (אופציונלי) אם מוצג מסך הרשאה, לוחצים על אישור.
  10. לוחצים על Exchange authorization code for tokens (החלפת קוד הרשאה באסימונים). מוחזר טוקן.
  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

JavaScript

תהליך ההגדרה

  1. פועלים לפי ההוראות בתיעוד של ה-API כדי ליצור פרויקט לאפליקציה או לבחור פרויקט קיים ולהפעיל את ה-API.
  2. יוצרים מפתח API במסוף Cloud.
  3. במסוף Cloud, יוצרים פרטי כניסה של מזהה לקוח OAuth עבור 'אפליקציית אינטרנט' ומגדירים את המקורות המורשים של JavaScript כדי לזהות את כתובת ה-URL שממנה יישלחו הבקשות, כמו http://localhost.
  4. מעתיקים את דוגמת הקוד המלאה לקובץ מקומי שאפשר לגשת אליו משרת האינטרנט, כמו /var/www/html/example.html.

  5. מחפשים בדוגמת הקוד את השורה שבה מוגדר מפתח ה-API או מזהה הלקוח, ומחליפים את הערך בערכים שנוצרו בשלבים 2 ו-3:

    • מפתח API: gapi.client.setApiKey(YOUR_API_KEY);
    • מזהה לקוח ב-OAuth 2.0: gapi.client.init({ 'clientId': 'YOUR_CLIENT_ID',

הפעלת דוגמת קוד

  1. פותחים את הקובץ בדפדפן, כמו http://localhost/example.html. מומלץ להשתמש בדפדפן עם מסוף לניפוי באגים, כמו Google Chrome.
  2. (אופציונלי) אם מוצג מסך כניסה, בוחרים את החשבון שבו רוצים להשתמש.
  3. (אופציונלי) אם מוצג מסך הרשאה, לוחצים על אישור. התגובה של השיטה אמורה להופיע במסוף הניפוי כ-JSON object.

Java

דרישות מוקדמות

  • ‫Java 1.7 ואילך.
  • ‫Gradle 7 ואילך.

תהליך ההגדרה

  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 בשלב 2, משנים את השם של קובץ ה-JSON שהורדתם ל-client_secret.json.

  7. שומרים את הקובץ ששמו שונה בספרייה src/main/resources שיצרתם בשלב 5.

  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 שקוראים לו. הנה דוגמה ל-YouTube Analytics API:

    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 שמופיע ב-GitHub עבור ה-API. כדי למצוא את השם, לוחצים על הקישור לגרסה שלצד ה-API בדף ממשקי Google API נתמכים. הקישור של הגרסה מעביר אל GitHub. שם ה-API מופיע באמצע החלק העליון של הדף ולפניו הסמל googleapis/google-apis-services-. לדוגמה, בגרסה 3 של Drive API, הערך של API_NAME הוא drive.
  • ‫API_VERSION היא גרסת ה-API שמופיעה עבור ה-API מתחת לשם ה-API בדף 'ממשקי Google APIs נתמכים'.
  • ‫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. אפשר גם לבדוק את השירות שאליו מתקשרים כדי לראות את ההשפעות של בקשות שכותבות נתונים.

Node.js

דרישות מוקדמות

  • Node.js

  • ספריית הלקוח של Google APIs ל-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

דרישות מוקדמות

  • ‫PHP 5.4 ומעלה עם ממשק שורת הפקודה (CLI) ותוסף JSON.
  • הכלי לניהול יחסי תלות ב-Composer מותקן באופן גלובלי.

  • ספריית הלקוח של Google APIs ל-PHP:

    • אם לא התקנתם בעבר את ספריית הלקוח, מריצים את הפקודה:

      composer require google/apiclient:^2.0

    • אם התקנתם בעבר את ספריית הלקוח, מומלץ לעדכן אותה כדי לוודא שיש לכם את המחלקות העדכניות ביותר בספרייה שאתם בודקים. כדי לעדכן את ספריית הלקוח, מריצים את הפקודה:

      composer update google/apiclient --with-dependencies

הפעלת דוגמת קוד

כדי להריץ את הדוגמה, משתמשים בפקודה הבאה:

  php sample.php

רוב הדוגמאות מדפיסות תגובה של API (או משהו אחר) ל-STDOUT.

Python

דרישות מוקדמות

  • ‫Python 2.7 או Python 3.5 ואילך
  • כלי ניהול החבילות pip

  • ספריית הלקוח של Google APIs ל-Python:

    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.

Ruby

דרישות מוקדמות

  • ‫Ruby 2.0 ואילך

  • ספריית הלקוח של Google APIs ל-Ruby:

    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.

פתרון בעיות שקשורות לדוגמאות

תיבת הדו-שיח של ההרשאה לא מופיעה

ב-APIs Explorer נעשה שימוש בחלון קופץ כדי להעניק גישה לנתונים הפרטיים שלכם. אם הדפדפן חוסם חלונות קופצים, החלון הקופץ הזה לא יופיע ולא תוכלו להעניק גישה.

אם לוחצים על 'אישור' במסך ההרשאה וכלום לא קורה, צריך לנסות לשנות את הגדרות החלונות הקופצים בדפדפן כדי לאפשר את פתיחתם.

קיבלת שגיאה מסוג 401 או 403

אם אתם מקבלים שגיאה 401 או 403 כשאתם בודקים דוגמה, סביר להניח שהבעיה היא באחד מהדברים הבאים:

  • ה-API לא מופעל בפרויקט. קוראים את ההוראות של ממשק ה-API כדי לדעת איך ליצור פרויקט ולהפעיל ממשק API.
  • אתם משתמשים בסוג הרשאה שגוי (מפתח API במקום OAuth 2.0).
  • אתם משתמשים ב-OAuth 2.0, אבל בהיקף צר מדי.
  • כשמגדירים את מפתח ה-API, מגדירים גם הגבלות כדי למנוע שימוש לא מורשה בפרטי הכניסה. עם זאת, הבקשה לא עומדת בהגבלות האלה. מידע נוסף זמין במאמר בנושא שימוש בהגבלות על מפתחות API.

קיבלת אזהרה לגבי תוכן מעורב

אם אתם משתמשים ב-Google Cloud Endpoints ומפעילים את נקודת הקצה בשרת פיתוח, יכול להיות שבדפדפן תוצג אזהרה לגבי תוכן מעורב. האזהרה הזו מופיעה כי API Explorer נטען באמצעות HTTPS, אבל כשה-API פועל באופן מקומי, הוא מתארח ב-HTTP.

כדי להסתיר את האזהרה הזו באמצעות Chrome, צריך להתחיל סשן Chrome עם פקודות מיוחדות באופן הבא:

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

מומלץ להסתיר את האזהרה הזו רק למטרות בדיקה מקומיות.

‫JavaScript בלבד: gapi לא מוגדר

השגיאה gapi is not defined מתרחשת כשקוד JavaScript מנסה לקרוא לספריית הלקוח של Google API ל-JavaScript לפני שהספרייה נטענה. חשוב לוודא שהקוד שמפנה למשתנה gapi לא נקרא עד שטעינת ספריית הלקוח מסתיימת.