תחילת העבודה עם ספריית הלקוח של PHP של נתוני Google

אזהרה: דף זה עוסק בממשקי API הישנים יותר של Google, בממשקי ה-API של נתוני Google, והוא רלוונטי רק לממשקי ה-API שרשומים בספריית ממשקי ה-API של נתוני Google, שרבים מהם הוחלפו בממשקי API חדשים יותר. למידע על API חדש ספציפי, עיינו במסמכי התיעוד של ה-API החדש. למידע על הרשאת בקשות באמצעות ממשק API חדש יותר, יש לעיין בקטע אימות והרשאה של חשבונות Google.

סרטון: צפו ב-Trevor Johns בתהליך התקנת ספריית לקוח, ארכיטקטורת ספרייה והדרכה קולית על קודים.

ג'וקן הרטמן, צוות Google Data APIs
עודכן באוקטובר 2008 (פורסם במקור על ידי דניאל הולוו))

מבוא

ספריית הלקוחות של PHP של Google Data היא אוסף חזק של כיתות שמאפשרות לך להשתמש ב-Google Data APIs. בניגוד לספריות הלקוח האחרות שלנו, החבילה של החבילה היא חלק מ-Zend Framework הפופולרי, אבל אפשר להוריד אותה גם בנפרד. בדומה לספריות הלקוח האחרות שלנו, גם היא מבוססת על קוד פתוח ומיועדת להיות פשוטה ויעילה, כך שתוכלו להתחיל לעבוד על הפרויקטים שלכם במהירות.

התקנה מראש

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

<?php phpinfo(); ?>

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

צילום מסך של דף המידע של php

בצילום המסך מוצג דף הפרטים של PHP. דף זה מציג את גרסת ה-PHP שהותקנו (5.2.6 במקרה הזה), יחד עם התוספים שהופעלו (בקטע 'הגדרת פקודה') ואת המיקום של קובץ התצורה הפנימי של PHP (בקטע 'קובץ תצורה שנטענת'). אם הדף לא מוצג או אם גרסת ה-PHP שלך ישנה יותר מ-5.1.4, צריך להתקין או לשדרג את גרסת ה-PHP. אחרת, אפשר לדלג על הקטע הבא ולהמשיך להתקין את ספריית הלקוח של PHP.

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

התקנת PHP

ההתקנה משתנה מעט בהתאם לפלטפורמה, לכן חשוב לבצע את ההוראות עבור הפלטפורמה הספציפית שלך במהלך ההתקנה. לפני שנצלול לעומק, כדאי לציין שהפופולריות של חבילות שהותקנו מראש ושכוללות את שרת האינטרנט Apache ואת מסד הנתונים MySQL, כמו גם את PHP, זכתה לפופולריות. ב-Windows, ב-Mac OS X וב-Linux, קיים פרויקט XAMPP. משתמשי Mac OS X יכולים גם להשתמש בפרויקט AMP. שתי החבילות תומכות ב-OpenSSL ב-PHP (נדרש לאינטראקציה עם פידים מאומתים).

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

ב-Windows

הדרך הקלה ביותר להתקין או לשדרג PHP ב-Windows היא באמצעות מתקין PHP הזמין בדף הורדות PHP.

  1. בחר באפשרות מנהל ההתקנה של PHP (בקטע הבינארי של Windows) התואמת לגרסה החדשה ביותר של PHP ואפשר לה להוריד.
  2. פותחים את מנהל ההתקנה ופועלים לפי הוראות אשף ההתקנה.
  3. כאשר האשף מבקש ממך אישור, בחר את שרת האינטרנט שמותקן במערכת שלך, כך שהוא יגדיר את השרת לפעול עם PHP.
  4. בדוק את ההתקנה על ידי ביצוע השלבים המתוארים בקטע שלמעלה.

ב-Mac OS X

PHP כלול ב-OS X, אבל לפני השימוש צריך לשדרג לגרסה האחרונה של PHP. כדי לשדרג, ניתן להתקין כל אחת מהחבילות הבינאריות בחינם או להדר אותה בעצמך. לפרטים, עיין בדף התיעוד של PHP בנושא התקנה ב-Mac OS X.

לאחר התקנה או הגדרה אחרת של OS X, יש לבדוק את ההתקנה על ידי ביצוע השלבים המתוארים בקטע ההתקנה מראש של מסמך זה.

ב-Linux

בהתאם להפצת Linux, ייתכן שיש אפשרות הגדרה מובנית או קלה לשימוש עבור התקנת PHP. לדוגמה, ב-Ubuntu אפשר להשתמש במנהל חבילות או פשוט להקליד את הטקסט הבא במסוף:

sudo apt-get install php5

אם אין התקנה ארוזה שזמינה בהפצה של Linux, עליך להתקין מקוד המקור. יש הוראות מפורטות לעריכת PHP עבור Apache 1.3 ולעריכת PHP עבור Apache 2. ל-PHP.net יש גם הוראות עבור שרתים אחרים.

התקנת ספריית הלקוח PHP של נתוני Google

עכשיו, לאחר שהתקנתם גרסת PHP פעילה, הגיע הזמן להתקין את ספריית הלקוחות. ספריית הלקוח היא חלק מ-Zend Framework של הקוד הפתוח, אבל אפשר להוריד אותה גם כגרסה עצמאית. אם כבר התקנת גרסה של Zend Framework (בגרסה 1.6 ואילך), תוכל לדלג על ההתקנה מפני שספריית הלקוחות של Google Data כלולה. עם זאת, כדי לוודא שאתם משתמשים בגרסה העדכנית ביותר של המסגרת, תקבלו את כל התכונות החדשות ותיקוני הבאגים הזמינים לכם, לכן מומלץ בדרך כלל.

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

  1. מורידים את הקבצים של ספריית הלקוחות של Google Data. (חפשו בדף "ממשקי API של נתונים של Google".)
  2. מבטלים את דחיסת הקבצים שהורדתם. אפשר ליצור ארבע ספריות משנה:
    • demos — אפליקציות לדוגמה
    • documentation — תיעוד של הקבצים בספריית הלקוח
    • library — קובצי המקור של ספריית הלקוח עצמם.
    • tests — קובצי בדיקה של יחידה לבדיקה אוטומטית.
  3. הוספת המיקום של התיקייה library לנתיב של ה-PHP (יש לעיין בקטע הבא)

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

השלב האחרון הוא לוודא שאתם יכולים לכלול את קובצי ספריית הלקוח של PHP ולכלול אותם מהספרייה שאתם בונים את הפרויקט. ניתן לעשות זאת על ידי הגדרת המשתנה include_path בקובץ התצורה של PHP (php.ini). המשתנה include_path מכיל מספר מיקומים של ספריות, שה-PHP בודק בעת הצהרה של require או include שמושכת מחלקות, ספריות או קבצים חיצוניים לסקריפט הנוכחי, בדומה למשפט import ב-Java. עליך לצרף את המיקום של קובצי ספריית הלקוח למה שכבר הוגדר בinclude_path שלך. ניתן לעשות זאת בשתי דרכים (לשתיהן מוסבר בפירוט):

  • הגדרה קבועה של הנחיית include_path בקובץ התצורה php.ini בשורת הפקודה – נדרשת גישת מעטפת וכתיבה.
  • מגדירים את משתנה הנתיב include_path ברמת ה'ספרייה' – נדרשים שרת האינטרנט Apache ויכולת ליצור קובצי .htaccess.
  • ניתן להשתמש בפונקציה set_include_path() כדי להגדיר באופן דינמי את הנתיב להכללה בסקריפטים .אפשר להגדיר אותה באופן דינמי בכל קובץ .php

אם יש לך הרשאת כתיבה והרשאות גישה לקובץ php.ini (או אם כותבים קוד במחשב המקומי), צריך לבצע את ההוראות המפורטות בנספח א'. אם אתם משתמשים בשרת האינטרנט Apache ויכולים ליצור קובצי .JAWS, תוכלו להגדיר את המשתנה include_path ברמת "לכל ספרייה". כלומר, כל הקבצים בספרייה שאתם משתמשים בהם יכולים להפנות באופן אוטומטי לספריית הספרייה של הלקוח.

ניתן לציין אפשרויות הגדרה של PHP כפי שמוצג בקטע הקוד הבא:

# This works for PHP5 in both Apache versions 1 and 2
<IfModule mod_php5.c>
  php_value include_path        ".:/usr/local/lib/php:/path/to/ZendGdata/library"
</IfModule>

הערה: מידע נוסף על שינוי הגדרות התצורה זמין במדריך PHP.

אם אין לכם גישת מעטפת לשרת שלכם, ואתם לא יכולים לשנות או ליצור קובצי .HTTPS שבהם אפשר להשתמש תמיד בפונקציה set_include_path. ייתכן שכבר הגדרת ערך מסוים ל-include_path שלך, לכן כדאי לפעול לפי המודל שבהמשך כדי להוסיף את הערכים החדשים, במקום להחליף את כל הנתיב:

$clientLibraryPath = '/path/to/ZendGdata/library';
$oldPath = set_include_path(get_include_path() . PATH_SEPARATOR . $clientLibraryPath);

הערה: מידע נוסף על הפונקציה set_include_path זמין בדפים ידניים של PHP.

הפעלת בודק ההתקנה של PHP

כדי לוודא שנתיב ההכללה הוגדר כהלכה, ניתן להריץ את הסקריפט PHS של בודק ההתקנה. פשוט מעתיקים את התוכן של הקובץ ומדביקים אותו בקובץ חדש בספרייה שזמינה באינטרנט בשרת שלכם, ועוברים אליו מהדפדפן. אם מופיע פלט דומה לפלט הבא, פירוש הדבר שהכול הוגדר כראוי והכול מוכן לשימוש בספריית הלקוח של PHP:

צילום מסך של הפלט של בדיקת ההתקנה של php

אם מוצגות שגיאות (כמו בצילום המסך שבהמשך), צריך לוודא שפעלתם לפי הכיוון. ייתכן שחסרים לכם תוספים או שהנתיב עדיין לא הוגדר כראוי. חשוב לזכור: ייתכן שתצטרכו להפעיל מחדש את השרת כדי שהשינויים ייכנסו לתוקף. האפשרות הזו רלוונטית רק אם משנים בפועל את הקובץ php.ini. בצילום המסך הבא אפשר לראות שהשדה include_path מוגדר לערך /path/to/nowhere:

צילום מסך של הפלט של בדיקת ההתקנה של php

הערה: שימו לב: בודק ההתקנה של PHP בודק את הפריטים הבאים ברצף: (1) אלו הם תוספי ה-PHP הנדרשים שהותקנו, (2) מפנה include_path אל הספרייה של ספריית הלקוח של PHP, (3) ניתן ליצור חיבורי SSL ולבסוף, יכול להיות חיבור אל ממשק API של נתוני YouTube. אם בדיקה מסוימת נכשלה, שאר הבדיקות לא ירוצו.

לאחר שספריית הלקוח מותקנת, הגיע הזמן לנסות את הדוגמאות.

הרצת הדוגמאות

בבסיס של ספריית Zend/Gdata יש תיקייה של הדגמות — דוגמאות שיעזרו לך להתחיל. חלק מהדוגמאות האלה מיועדות להפעלה משורת הפקודה, כגון demos/Zend/Gdata/Blogger.php ו-demos/Zend/Gdata/Spreadsheet-ClientLogin.php, וניתן לבצע אותן באמצעות php /path/to/example. את שאר הדוגמאות אפשר להריץ גם משורת הפקודה וגם מדפדפן אינטרנט. כדי להציג אותם בדפדפן, יש למקם אותם בכל ספרייה שבה תשתמשו להצגת דפי אינטרנט. הדוגמאות האלה אמורות לספק מושג בסיסי לגבי כתיבה והפעלה של אפליקציה של נתוני Google, אבל כשתהיו מוכנים לקבל מידע נוסף, תוכלו להיעזר במשאבים אחרים של המתכנת הסקרן.

הערה: אם ברצונך לראות הדגמות באינטרנט המבוססות על האינטרנט, יש להיכנס לכתובת googlecodesample.com ולחפש את אפליקציות ה-PHP.

איפה אפשר למצוא מידע נוסף

המקומות הטובים ביותר לחפש מידע על הכיתות שהן חלק מספריית הלקוחות הם מדריך עזר ל-API באתר Zend Framework. חשוב לבחור את החבילה Zend_Gdata מהתפריט הנפתח.

בשלב הזה אתם מוכנים להתחיל בתכנות. אז קדימה, רשמו כמה אפליקציות נהדרות. אנחנו מצפים בקוצר רוח לראות את התוצאות שלך!

ניתן למצוא מדריכים למפתחי PHP עבור השירותים הבאים:

מאחר שספריית הלקוחות של PHP היא פרויקט קוד פתוח, נמשיך להוסיף תמיכה לממשקי API נוספים. לכל שירות יש קבוצת תמיכה משלו. מידע נוסף זמין בדף השאלות הנפוצות שלנו.

אם אתם צריכים עזרה בפתרון בעיות הקשורות לקריאות ל-API, אפשר לקרוא מאמרים על ניפוי באגים בבקשות API באמצעות כלים לתיעוד תנועת גולשים ברשת ועל שימוש בשרתי proxy עם ממשקי API של Google Data. יש גם מספר מאמרים חיצוניים הזמינים בהתקנת XAMPP ב-Linux ובהתקנת XAMPP ב-Windows. בנוסף לכל המאמרים האלה, כדאי גם לקרוא את הפוסטים על ספריית הלקוח של PHP בבלוג הטיפים של Google Data API.

נספח א': עריכת נתיב ה-PHP בקובץ התצורה שלך ב-php.ini

נתיב PHP הוא משתנה שמכיל רשימה של מיקומים ש-PHP מחפש כאשר הוא מחפש ספריות נוספות במהלך הטעינה. כדי לאפשר ל-PHP לטעון את קובצי ספריית הלקוח של PHP של Google ולגשת אליהם במחשב או בשרת, יש למקם אותם במיקום שעליו ידוע ל-PHP. לחלופין, יש לצרף את מיקום הקבצים לנתיב ה-PHP. הערה: שינויים בקובץ php.ini בדרך כלל מחייבים הפעלה מחדש של השרת. תמיד אפשר לאמת את הערך הנוכחי של המשתנה include_path. לשם כך, נכנסים לדף פרטי ה-PHP שהצגנו קודם. מחפשים את התא קובץ תצורה שנטען בטבלה הראשונה ומחפשים את הנתיב בעמודה שמשמאל.

הערה: אם אתם משתמשים ב-php משורת הפקודה, ייתכן שתצטרכו לשנות משתנה נתיב נוסף. חשוב לעיין בנספח ב': שימוש ב-PHP משורת הפקודה.

לאחר איתור הקובץ php.ini, פועלים לפי השלבים הבאים כדי להוסיף אותו לנתיב.

  1. פותחים את הקובץ php.ini בעורך הטקסט המועדף עליכם.
  2. מחפשים את הקו של נתיב ה-PHP, שמתחיל בערך include_path.
  3. ניתן להוסיף את הנתיב ששמרת ב-Zend Framework לרשימת המיקומים שכבר קיימים, לפני תחילת הנתיב החדש עם המפריד הייעודי ל-OS (: במערכות דמויי Unix, ; ב-Windows). נתיב נכון במערכות כמו Unix ייראה בערך כך: 
    /path1:/path2:/usr/local/lib/php/library
    ב-Windows, הוא ייראה בערך כך: 
    \path1;\path2;\php\library
  4. שומרים וסוגרים את הקובץ.

הערה: ב-Mac OS X, Finder אינו מאפשר גישה לקבצים שנמצאים במיקומי המערכת, כמו הספרייה /etc. לכן יהיה קל יותר לערוך אותם באמצעות עורך שורות פקודה כמו vi או pico. לשם כך צריך להשתמש בפקודה כמו: pico /path/to/php.ini.

נספח ב': שימוש ב-PHP משורת הפקודה

החל מגרסה 5 של PHP, יש כלי עזר לשורת הפקודה שזמין ב-PHP, ומכונה 'CLI' ל'מתורגמן בשורת הפקודה'. השימוש בכלי השירות הזה מאפשר הפעלה של סקריפטים של php משורת הפקודה. המצבים שבהם מצב זה יכול להיות שימושי הם אם אתם מפעילים PHP באופן מקומי במחשב ומחפשים דרכים לבדוק במהירות סקריפטים מסוימים. לשם כך, תצטרכו גישה למעטפת בשרת שלכם. חשוב לשים לב לכך ש-PHP משתמש בדרך כלל בשני קובצי php.ini נפרדים, אחד מכיל את אפשרויות התצורה עבור PHP שפועלות בשרת, ואחד עבור תצורות שבהן PHP משתמש בעת הפעלה משורת הפקודה. אם ברצונך להריץ את אפליקציות ההדגמה של שורת הפקודה מספריית הלקוח, יש לשנות גם את הקובץ php.ini בשורת הפקודה.

כדי לאתר אותה, מקלידים את הפקודות הבאות במערכות דמויי Unix (Mac OS X , Linux ואחרות):

php -i | grep php.ini

הפקודה אמורה להציג את המידע הבא בטרמינל:

Configuration File (php.ini) Path => /etc/php5/cli
Loaded Configuration File => /etc/php5/cli/php.ini

הערה: כמובן שמיקומי הנתיבים בפועל (/etc/php...) עשויים להשתנות במערכת שלך.

נספח ג': רמזים ופתרונות

בקטע הזה מתוארים בקצרה חלק מהבעיות שהמפתחים גילו במהלך העבודה עם PHP והפתרונות המתאימים.

בעיה בתוסף do-xml ב-XAMPP

ספריית הלקוח של PHP משתמשת במחלקות DOMDOCUMENT כדי להמיר בקשות ותגובות של XML לאובייקטים של PHP. התוסף dom-xml עלול לגרום לבעיות בטיפול ב-XML ולגרום לטרנספורמציות שגויות. חלק מהמפתחים שלנו גילו שכאשר הם משתמשים ב-XAMPP, בנאי DOMDocument מקבל עדיפות על ידי קריאה לפונקציה ישנה יותר, כפי שמוסבר באתר ה-PHP. כדי לפתור את הבעיה, יש לוודא שהטיפול ב-XML לא מבוטל בקובץ ה-php.ini. חשוב להסיר את ההפניות אל php_domxml.dll מקובץ התצורה.

פג הזמן הקצוב של בקשות בעת שימוש בספריית הלקוח

אם אתם משתמשים בספריית הלקוחות כדי לבצע בקשות גדולות למדי, כמו העלאת סרטונים ל-YouTube Data API, ייתכן שתצטרכו לשנות את הפרמטר timeout בכיתה Zend_Http_Client. ניתן לעשות זאת בקלות על ידי העברת פרמטר $config במהלך רגע, שמגדיר את הערך timeout לערך שונה מברירת המחדל של 10 שניות:

// assuming your Zend_Http_Client already exists as $httpClient
// and that you want to change the timeout from the 10 second default to 30 seconds

$config = array('timeout' => 30);
$httpClient->setConfig($config);

ספקי אירוח מסוימים לא מאפשרים ליצור חיבורי https מהשרתים שלהם

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

Unable to Connect to sslv2://www.google.com:443. Error #110: Connection timed out

ספק האירוח צריך לכלול מידע על הכתובת בפועל של שרת ה-proxy לשימוש. קטע הקוד הבא מדגים איך ניתן להשתמש בתצורת שרת proxy בהתאמה אישית עם ספריית הלקוח של PHP:

// Load the proxy adapter class in addition to the other required classes
Zend_Loader::loadClass('Zend_Http_Client_Adapter_Proxy');

// Configure the proxy connection with your hostname and portnumber
$config = array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'your.proxy.server.net',
    'proxy_port' => 3128
);

// A simple https request would be an attempt to authenticate via ClientLogin
$proxiedHttpClient = new Zend_Http_Client('http://www.google.com:443', $config);

$username = 'foo@example.com';
$password = 'barbaz';

// The service name would depend on what API you are interacting with, here
// we are using the Google DocumentsList Data API
$service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;

// Try to perform the ClientLogin authentication using our proxy client.
// If there is an error, we exit since it doesn't make sense to go on.
try {

  // Note that we are creating another Zend_Http_Client
  // by passing our proxied client into the constructor.

  $httpClient = Zend_Gdata_ClientLogin::getHttpClient(
      $username, $password, $service, $proxiedHttpClient);

} catch (Zend_Gdata_App_HttpException $httpException) {

  // You may want to handle this differently in your application
  exit("An error occurred trying to connect to the proxy server\n" .
      $httpException->getMessage() . "\n");

}

היסטוריית גרסאות

1 באוקטובר 2008

עודכן על ידי יוכן הרטמן. העדכון הזה כולל את השינויים הבאים:

  • הגדרת ה-PHP עבור שרתי האינטרנט הייתה ברורה יותר על ידי העברת קטעים שמתייחסים ל-PHP בשורת הפקודה לנספח.
  • נוספה הערה לגבי מספר קובצי תצורה של php.ini.
  • הוספנו קטעים שמסבירים איך להגדיר את ה-include_path באופן דינמי.
  • נוסף קטע בסקריפט של בודק ההתקנה.
  • נוסף קישור לדוגמאות באינטרנט.
  • נוספו קישורים ל-XAMPP ול-MAMP.
  • נוסף נספח 'רמזים ופתרונות'.