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

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

חלונית מסך מלא של 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.

כתובת אתר

הגדרה

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

Java

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

  • גרסת Java 1.7 ואילך.
  • גרסה 7 ומעלה.

הגדרה

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

ביצוע קוד לדוגמה

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

  node sample.js

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

PHP

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

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

  • ספריית הלקוחות של 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 ואילך
  • הכלי לניהול חבילות התמונות

  • ספריית הלקוח של 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 כדי ליצור או לבחור פרויקט לאפליקציה שלכם ולהפעיל אותו.
  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 והמיקום של ערכי ה-Secret של הלקוח הוא YOUR_CLIENT_SECRET_FILE.json.

ביצוע קוד לדוגמה

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

  python sample.py

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

Ruby

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

  • רובי 2.0 ומעלה

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

    gem install google-api-client`

הגדרה

  1. פועלים לפי ההוראות במסמכי ה-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 והמיקום של ערכי ה-Secret של הלקוח הוא YOUR_CLIENT_SECRET_FILE.json.

ביצוע קוד לדוגמה

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

  ruby sample.rb

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

פתרון בעיות לדוגמה

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

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

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

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

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

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

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

אם אתם משתמשים ב-Google Cloud Endpoints ואתם מפעילים את נקודת הקצה בשרת פיתוח, יכול להיות שתוצג בדפדפן אזהרה לגבי תוכן מעורב. האזהרה הזו מופיעה מכיוון ש-APIs 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 לא מוגדרת" מתרחשת כאשר קוד JavaScript מנסה לקרוא לספריית הלקוח של Google API עבור JavaScript לפני הטעינה של הספרייה. ודאו שהקוד המתייחס למשתנה gapi לא נקרא עד שתסתיים הטעינה של ספריית הלקוח.