דף זה תורגם על ידי Cloud Translation API.

שימוש בספריית הלקוח של JavaScript (גרסה 2.0)

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

מסמך זה מתאר כיצד להשתמש בספריית הלקוח של JavaScript כדי לשלוח שאילתות Google Data API ולפרש תשובות שהוחזרו.

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

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

Audience

המסמך הזה מיועד למתכנתים ב-JavaScript שרוצים לכתוב אפליקציות לקוח שמקיימות אינטראקציה עם שירותי הנתונים של Google.

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

למידע נוסף על המחלקות והשיטות שסופקו על ידי ספריית הלקוח, עיינו בחומר העזר בנושא ספריות JavaScript של הלקוח (בפורמט JSdoc).

המסמך הזה קריא לקריאה, וכל דוגמה מבוססת על דוגמאות קודמות.

תנאים והגבלות

את/ה מסכים/ה לציית לתנאים ולהגבלות של ספריית JavaScript של Google בעת השימוש בספריית לקוח JavaScript.

סקירה כללית של מודל נתונים וזרימת בקרה

ספריית הלקוח של JavaScript משתמשת בקבוצה של מחלקות כדי לייצג את הרכיבים המשמשים את Google Data APIs.

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

הספרייה מספקת שיטות שמאפשרות לשלוח נתונים באופן אסינכרוני ולקבל נתונים משירות שכולל ממשק API לנתונים. לדוגמה, השיטה google.gdata.calendar.CalendarService.getEventsFeed() שולחת בקשה לעדכון אל יומן Google. אחד מהפרמטרים שאתם מעבירים הוא פונקציית המשך, שנקראת גם קריאה חוזרת (callback). השירות מחזיר את הפיד בפורמט JSON על ידי קריאה לפונקציית המשך. לאחר מכן הלקוח יכול לקרוא לשיטות שונות של get כדי להשתמש בנתונים כאובייקטים של JavaScript.

כדי להוסיף רשומה חדשה, עליך ליצור את הערך באמצעות המחלקות והשיטות של ספריית הלקוח, ולאחר מכן לקרוא לשיטה feed.insertEntry() כדי לשלוח את הערך החדש לשירות. שוב תספק פונקציית המשך, שאליה השירות יקרא לאחר שהרשומה תתווסף בהצלחה.

אם זו הפעם הראשונה שאתם משתמשים ב-JavaScript, תהליך הבקרה עלול להיות קצת מבלבל. אחרי קריאה לשיטה כמו getEventsFeed() או insertEntry(), ברוב המקרים הסקריפט יסתיים. הפעולה תמשיך בפונקציית המשך כשהשירות יחזיר את הנתונים המבוקשים. לכן, כל פעולה שהלקוח מבצע בנתונים שמוחזרים צריכה להתבצע בפונקציית המשך, או שתיקרא מפונקציה זו. לפעמים צריך ליצור משתנים גלובליים כדי להשתמש בהם בכמה פונקציות.

למידע נוסף על סגנון התכנות הזה, עיינו בוויקיפדיה "המשך המשכיות".

מידע על סביבות נתמכות

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

Firefox 2.x ו-3.x
Internet Explorer 6, 7 ו-8
Safari 3.x ו- 4.x
Google Chrome (כל הגרסאות)

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

במאמר סקירה כללית של אימות ממשקי API של נתונים של Google אפשר לקרוא סקירה כללית על אימות של ממשקי API של נתונים של Google. בהמשך המסמך אנו מניחים שאתה מכיר את היסודות של אופן הפעולה של המערכת.

אפליקציות לדוגמה

כדי לראות את ספריית הלקוח של JavaScript בפעולה, בקר בדף הדוגמאות.

מדריך ודוגמאות

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

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

הספרייה בטעינה

כדי שהלקוח יוכל להשתמש בספריית הלקוח, עליו לבקש את הקוד של ספריית הלקוח מהשרת.

התחל באמצעות התג <script> בקטע <head> של מסמך ה-HTML, כדי לאחזר את טוען ה-API של AJAX של Google:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

אפשר לצמצם את זמן הלוך ושוב לשרתים של Google ולצמצם את זמן האחזור על ידי טעינה מראש של הספרייה. כדי לטעון מראש חבילות מסוימות ישירות מטוען ה-API של Google AJAX (בלי להשתמש ב-google.load() בהמשך), יש להשתמש באפשרויות הבאות:

<script type="text/javascript"
      src="https://www.google.com/jsapi?autoload=%7Bmodules%3A%5B%7Bname%3Agdata%2Cversion%3A2.x%2Cpackages%3A%5Bblogger%2Ccontacts%5D%7D%5D%7D"></script>

הערה: כתובת ה-URL של הסקריפט src צריכה להיות מקודדת במלואה. לדוגמה, הדוגמה הקודמת היא
<script type="text/javascript" src="https://www.google.com/jsapi?autoload={modules:[{name:gdata,version:2.x,packages:[blogger,contacts]}]}"></script>.

אם לא מתבצעת טעינה אוטומטית של מודולים, ניתן לטעון את ספריית הלקוחות של Google Data באמצעות הדוגמה הבאה בקוד הגדרת ה-JavaScript, לאחר אחזור הטוען הנפוץ. יש לבצע את הקריאה הזו מהקטע <head> של מסמך ה-HTML (או מקובץ JavaScript הכלול בתג <script> בקטע <head> של מסמך ה-HTML):

google.load("gdata", "2");

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

google.load("gdata", "2.x", {packages: ["blogger", "contacts"]});

הפרמטר השני של google.load() הוא מספר הגרסה המבוקשת של ספריית הלקוח ב-JavaScript.הסכימה של מספור הגרסאות מבוססת על התבנית שבה נעשה שימוש ב-Google Maps API. הנה מספרי הגרסאות האפשריים והמשמעות שלהם:

"1": הגרסה השנייה מהאחרונה בגרסה 1.
"1.x": הגרסה האחרונה לגרסה 1.
"1.s": הגרסה האחרונה היציבה של גרסה 1 קודם. מדי פעם נכריז על גרסה מסוימת של ספריית הלקוחות בתור "יציבה", על סמך המשוב שאנחנו מקבלים ממפתחים. עם זאת, ייתכן שהגרסה הזו לא כוללת את התכונות העדכניות ביותר.
"1.0", "1.1" וכו': גרסה ספציפית של הספרייה, עם מספר משמעותי של גרסה ראשית או משנית.

אחרי שהתקשרת ל-google.load(), עליך לומר לפותר הבעיות להמתין עד שהדף יסיים להיטען ואז להתקשר לקוד שלך:

google.setOnLoadCallback(getMyFeed);

כאשר getMyFeed() היא פונקציה המוגדרת בקטע הבא של מסמך זה. מומלץ להשתמש בגישה הזו במקום לצרף רכיב handler של onload לרכיב <body>.

איך שולחים פיד לא מאומת

כדי לבקש פיד לא מאומת, צריך להוסיף את הקוד הבא לקובץ ה-JavaScript או להוסיף תג <script> לקובץ ה-HTML.

בקוד הבא, getMyFeed() מתחיל בקריאה ראשונה (על ידי הכלי לטעינת AJAX API, כפי שמתואר בקטע הקודם).

הוא מבצע קריאה ל-setupMyService() ליצור חיבור (המיוצג על ידי אובייקט של יומן שירות) ביומן Google. שלפנו את הקוד ליצירת שירות לפונקציה נפרדת של מודולריות. לאחר מכן, אנחנו נחליף את הפונקציה setupMyService() בהתאם לאפשרויות האימות שבחרת.

לאחר הגדרת השירות, getMyFeed() מתקשרת למתודה getEventsFeed() של ספריית הלקוח כדי לבקש את הפיד.

אנחנו מציינים את כתובת ה-URL של הפיד במשתנה גלובלי כדי שניתן יהיה להשתמש בו בפונקציות הבאות. בדוגמה זו אנחנו משתמשים בכתובת ה-URL של הפיד הציבורי (הלא מאומת) בשביל משתמש בשם liz@gmail.com. אפשר גם להשתמש ב-default במקום בכתובת האימייל של המשתמש כדי לייצג את המשתמש המאומת.

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/public/full";

function setupMyService() {
  var myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
  return myService;
}

function getMyFeed() {
  myService = setupMyService();

  myService.getEventsFeed(feedUrl, handleMyFeed, handleError);
}

לתשומת ליבך: אנחנו הופכים את myService למשתנה גלובלי, כדי לאפשר לך להשתמש בקלות בקלות מאוחר יותר.

כדי להשתמש בקוד שלמעלה בחשבון של הלקוח שלכם, עליכם להשתמש בכתובת אימייל של משתמש אמיתי עבור חשבון ביומן עם יומן משותף באופן ציבורי.

הערה: כשיוצרים אובייקט חדש של CalendarService, ספריית הלקוח קוראת לשיטה בשם google.gdata.client.init(), שמאמתת שהדפדפן שבו הלקוח פועל נתמך. אם יש שגיאה, ספריית הלקוח מציגה הודעת שגיאה למשתמש. אם ברצונך לטפל בבעיה מסוג זה בעצמך, באפשרותך להתקשר ישירות אל google.gdata.client.init(handleInitError) לפני יצירת השירות, כאשר handleInitError() הוא הפונקציה שלך. אם מתרחשת שגיאת Init, הפונקציה מקבלת אובייקט שגיאה רגיל. ניתן לבצע כל פעולה באמצעות האובייקט הזה.

בשיחה אל getEventsFeed(), הארגומנט השני הוא handleMyFeed, שהוא פונקציית קריאה חוזרת. יש לעיין בהמשך. יומן Google מעבד את הבקשה, ואם הבקשה הצליחה מעבירה לאובייקט חזרה את האובייקט שמכיל את הפיד המבוקש. שורש של פיד הוא אובייקט של מאגר שמכיל פיד.

הארגומנט השלישי ל-getEventsFeed() הוא פונקציה אופציונלית לטיפול בשגיאות. אם ספריית הלקוח נתקלת בשגיאה, היא קוראת למפעיל השגיאות שצוין במקום לפונקציית הקריאה החוזרת המצליחה. האובייקט שספריית הלקוח מעבירה כארגומנט של מטפל השגיאות הוא מופע של אובייקט JavaScript Error, עם מאפיין cause נוסף.

הנה גרסאות פשוטות של פונקציית הקריאה החוזרת ושל הגורם המטפל בשגיאות:

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
}

function handleError(e) {
  alert("There was an error!");
  alert(e.cause ? e.cause.statusText : e.message);
}

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

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

מאמת

ניתן להשתמש בספריית הלקוח של JavaScript בשני מצבים. אם אתה כותב גאדג'ט, הוא משתמש בתכונה הנקראת Proxy של OAuth לאימות. אם מתבצעת גישה אליה מיישום JavaScript עצמאי, היא משתמשת במערכת האימות של OAuthSub. למידע על אימות, עיינו במסמך סקירה כללית על אימות ממשקי API של נתוני Google. בהמשך סעיף זה ההנחה היא שאתם מכירים את העקרונות הבסיסיים של מערכת זו.

לפני השימוש באימות באמצעות קוד לדוגמה המופיע במסמך זה, יש לשנות את כתובת ה-URL של הפיד מ'פרטי' ל'פרטי':

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/private/full";

אימות בלקוח אינטרנט באמצעות AuthSub

מערכת ההרשאות של AuthSub עבור JavaScript לא זמינה יותר.

במקום זאת, אנחנו ממליצים להשתמש ב-OAuth 2.0 לאפליקציות בצד הלקוח.

ביצוע אימות בגאדג'ט באמצעות שרת proxy של OAuth

הנה סקירה קצרה של מה שקורה בתהליך האימות של גאדג'ט:

הגאדג'ט שלך נטען בפעם הראשונה ומנסה לגשת לנתוני המשתמש דרך אחד מממשקי ה-API של Google Data.
הבקשה נכשלה כיוון שהמשתמש עדיין לא נתן גישה לנתונים שלו. אובייקט התשובה מכיל כתובת URL (ב-response.oauthApprovalUrl) של דף אישור ה-OAuth. הגאדג'ט שלך צריך לספק שיטה להשקת חלון חדש עם כתובת האתר הזו.
בדף האישור, המשתמש בוחר להעניק/לדחות גישה לגאדג'ט שלך. אם התגובה לבקשה מוצלחת, המשתמש מועבר לדף oauth_callback שציינת. כדי ליהנות מחוויית השימוש הטובה ביותר, מומלץ להשתמש באפליקציה http://oauth.gmodules.com/gadgets/oauthcallback.
לאחר מכן המשתמש סוגר את החלון הקופץ. כדי להודיע לגאדג'ט שלך שהמשתמש נתן את האישור, סיפקנו כלי handler לחלונות קופצים שבו ניתן להשתמש כדי לזהות את סגירת חלון האישור. לחלופין, הגאדג'ט שלך יכול להציג קישור (למשל, "אישרתי גישה") שהמשתמש יוכל ללחוץ עליו באופן ידני לאחר סגירת החלון.
הגאדג'ט שלך מנסה לגשת ל-Google Data API בפעם השנייה על ידי בקשת נתוני המשתמש מחדש. ניסיון זה בוצע בהצלחה.
הגאדג'ט שלך מאומת ויכול להתחיל לפעול כרגיל.

בגאדג'ט שלך, הוסף אלמנט <OAuth> בקטע <ModulePrefs>:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" /> 
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" /> 
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" /> 
  </Service>
</OAuth>
...
</ModulePrefs>

בקטע הזה, משנים את הפרמטרים הבאים של השאילתות:

scope
פרמטר נדרש בכתובת ה-URL של הבקשה. הגאדג'ט שלך יוכל לגשת לנתונים רק מ-scope שמשמשים את הפרמטר הזה. בדוגמה הזו, הגאדג'ט ייגש אל הנתונים של Blogger ושל יומן Google. גאדג'ט יכול לבקש נתונים עבור היקף יחיד או היקפים מרובים (כמו בדוגמה זו).
oauth_callback
פרמטר אופציונלי בכתובת ה-URL להרשאה. דף האישור של OAuth יופנה אוטומטית לכתובת ה-URL הזו אחרי שהמשתמש יאשר את הגישה לנתונים שלו. אפשר להשאיר את הפרמטר הזה מוגדר, להגדיר אותו כ"דף מאושר" משלכם או עדיף להשתמש ב-http://oauth.gmodules.com/gadgets/oauthcallback. בשלב מאוחר יותר, הוא יספק את חווית המשתמש הטובה ביותר בפעם הראשונה שהמשתמשים יתקינו את הגאדג'ט שלכם. הדף מספק קטע JavaScript שסוגר את החלון הקופץ באופן אוטומטי.

לאחר מכן, צריך לטעון את ספריית לקוח JavaScript בקטע <Content> של הגאדג'ט. משנים את הפונקציה setupMyService() בדוגמאות הקודמות, כדי לקרוא לשיטה useOAuth() של אובייקט השירות. פעולה זו מורה לגאדג'ט להשתמש בשרת ה-proxy של OAuth כדי לאמת במקום AuthSub. אתם יכולים להיעזר בתבנית הבאה:

<Content type="html">
<![CDATA[
  ...
  <script src="https://www.google.com/jsapi"></script>
  <script type="text/javascript">
    var myService = null;
    
    function setupMyService() {
      myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
      myService.useOAuth('google');
      fetchData();
    }
    
    function initGadget() {
      google.load('gdata', '2.x');
      google.setOnLoadCallback(setupMyService);
    }

    function fetchData() {            
      var callback = function(response) {
        if (response.oauthApprovalUrl) {
        
          // TODO: Display "Sign in" link (response.oauthApprovalUrl contains the URL) 
          
        } else if (response.feed) {
        
          // TODO: show results
          
        } else {
        
          // TODO: handle the error
          
        }
      };

      myService.getEventsFeed('http://www.google.com/calendar/feeds/default/public/full', callback, callback);
    }
    
    gadgets.util.registerOnLoadHandler(initGadget);
  </script>
  ...
]]> 
</Content>

לידיעתך, השיחה אל google.accounts.user.login(scope) הוסרה. שרת ה-proxy מטפל בשבילך באימות.

למידע נוסף על כתיבת גאדג'טים של Google Data API, כולל פרטים על מה שfetchData() צריך להכיל, עיין במאמר שלנו בנושא יצירת גאדג'ט של Google Data או עיין בתיעוד המלא של כתיבת גאדג'טים ל-OAuth.

הוספת פריט חדש

כדי ליצור אירוע חדש ביומן, צריך להמשיך את הביצוע מהדוגמה הקודמת על ידי שינוי הקצה של הפונקציה handleMyFeed() כדי לקרוא לפונקציה חדשה:

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
  insertIntoMyFeed(myResultsFeedRoot);
}

בפונקציה החדשה, תחילה משתמשים בבנאי CalendarEventEntry כדי ליצור את הערך החדש. לאחר מכן יש להוסיף את הערך ולהכניס קריאה חוזרת (callback) עבור השירות כדי שהוא יתקשר בסיום תהליך ההוספה.

function insertIntoMyFeed(feedRoot) {
  var newEntry = new google.gdata.calendar.CalendarEventEntry({
      authors: [{
        name: "Elizabeth Bennet",
        email: "liz@gmail.com"
      }],
      title: {
        type: 'text', 
        text: 'Tennis with Darcy'
      },
      content: {
        type: 'text', 
        text: 'Meet for a quick lesson'
      },
      locations: [{
        rel: "g.event",
        label: "Event location",
        valueString: "Netherfield Park tennis court"
      }],
      times: [{
        startTime: google.gdata.DateTime.fromIso8601("2007-09-23T18:00:00.000Z"),
        endTime: google.gdata.DateTime.fromIso8601("2007-09-23T19:00:00.000Z")
      }]
  });
  feedRoot.feed.insertEntry(newEntry, handleMyInsertedEntry, handleError);
}

חשוב לשים לב שהשם של כל מאפיין אובייקט המשמש בבנייה תואם לשם של שיטת מגדיר המשמשת עבור נכס זה. (במקום זאת, למשל, התאמה של שם שדה JSON המתאים).

כמו כן, לא ניתן רק לספק מחרוזות תאריך ושעה בפורמט ISO 8601 עבור startTime ו-endTime. תחילה עליך להריץ מחרוזות אלה באמצעות שיטת fromIso8601().

השירות מחזיר עותק של הערך שהוזן כאובייקט entryRoot, ומעביר את האובייקט חזרה לקריאה לפעולה:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
}

בקשת הגשה ספציפית

כדי לבקש ערך ספציפי, קודם צריך לשנות את הפונקציה handleMyInsertedEntry() כך שיקרא פונקציה חדשה של בקשת כניסה:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
  requestMySpecificEntry(insertedEntryRoot.entry.getSelfLink().getHref());
}

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

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

function requestMySpecificEntry(entryURI) {
  myService.getEventsEntry(entryURI, handleMySpecificEntry, handleError);
}

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
}

הדוגמה הזו זהה במהותה לדוגמה של getEventsFeed(), אבל אנחנו קוראים לשיטה getEventEntry() של השירות כדי לקבל ערך ספציפי, וה-URI שונה במקצת – היא משתמשת ב-default כברירת מחדל כדי להפנות ליומן הראשי של המשתמש המאומת, ובסופו יש מזהה כניסה.

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

מתבצע חיפוש ערכים

כדי לבצע חיפוש בטקסט מלא, צריך לשנות תחילה את הפונקציה handleMySpecificEntry() כדי לקרוא לפונקציית חיפוש חדשה:

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
  searchMyFeed();
}

כדי לאחזר את ההתאמה הראשונה מהחיפוש, משתמשים בקוד הבא:

function searchMyFeed() {
  var myQuery = new google.gdata.calendar.CalendarEventQuery(feedUrl);
  myQuery.setFullTextQuery("Tennis");
  myQuery.setMaxResults(10);
  myService.getEventsFeed(myQuery, handleMyQueryResults, handleError);
}

function handleMyQueryResults(myResultsFeedRoot) {
  if (myResultsFeedRoot.feed.getEntries()[0]) {
    alert("The first search-match entry's title is: " + myResultsFeedRoot.feed.getEntries()[0].getTitle().getText());
  }
  else {
    alert("There are no entries that match the search query.");
  }
}

עדכון פריט

כדי לעדכן פריט קיים, קודם צריך להוסיף שורה בסוף handleMyQueryResults() כדי להפעיל פונקציית עדכון חדשה:

  updateMyEntry();

לאחר מכן יש להשתמש בקוד הבא. בדוגמה הזו אנחנו משנים את הכותרת של הערך שאוחזר קודם (שנמצא באובייקט הגלובלי בשם myEntryRoot בדוגמה קודמת) מטקסט ישן ("טניס עם דארסי") ל"פגישה חשובה".

function updateMyEntry() {
  myEntryRoot.entry.getTitle().setText("Important meeting");
  myEntryRoot.entry.updateEntry(handleMyUpdatedEntry, handleError);
}

function handleMyUpdatedEntry(updatedEntryRoot) {
  alert("Entry updated. The new title is: " + updatedEntryRoot.entry.getTitle().getText());
}

כמו בכל השיטות של יומן Google, גם השיטה של updateEntry() קובעת באופן אוטומטי את ה-URI המתאים לעריכה לעדכון הרשומה, כך שלא צריך לספק את ה-URI הזה באופן מפורש.

מחיקת פריט

כדי למחוק את הרשומה המעודכנת, צריך להוסיף שורה ל-handleMyUpdatedEntry():

 deleteMyEntry(updatedEntryRoot);

לאחר מכן צריך להשתמש בקוד הבא:

function deleteMyEntry(updatedEntryRoot) {
  updatedEntryRoot.entry.deleteEntry(handleMyDeletedEntry, handleError);
}

function handleMyDeletedEntry() {
  alert("Entry deleted");
}

שוב, השיטה deleteEntry() קובעת באופן אוטומטי את ה-URI לעריכה הנכון לשימוש במחיקת הערך.

לתשומת ליבכם, לא מוחזרת רשומה. אם הקריאה החוזרת נקראת, אנחנו יודעים שהמחיקה הצליחה. אם המחיקה נכשלה, deleteEntry() מתקשר אל handleError() במקום להתקשר אל handleMyDeletedEntry().

שימוש ב-ETags

הערה: ניתן להשתמש ב-ETags רק בשירותים שבהם פועל Google Data Protocol v2.0.

מבוא

גרסה 2 של לקוח נתוני Google JavaScript כוללת תמיכה ב-ETags. תגים אלקטרוניים הם מזהים שמציינים גרסה מסוימת של רשומה מסוימת. הדבר חשוב בשני מקרים:

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

יש שני סוגים של ETags: חלשים וחזקים. ETag חלש תמיד מתחיל ב-W/, לדוגמה: W/"D08FQn8-eil7ImA9WxZbFEw". לא ניתן להבטיח ש-ETags חלשים ישתנו כשרשומה תשתנה, ולכן HTTP מאפשר להשתמש בהם רק לאחזור מותנה. ETags חזקים מזהים גרסה ספציפית של ערך ספציפי, וניתן להשתמש בהם גם לאחזור מותנה ובמהלך עדכונים או מחיקות כדי להימנע מהחלפה בשינויים של לקוחות אחרים. עקב ההבדל הזה, ספריית הלקוח לא תאפשר לכם לשלוח ETags חלשים עם בקשה לעדכון או למחיקה.

ניתן למצוא ETags בשני מיקומים בתגובת השרת:

בכותרת ה-HTTP ETag.
בפיד/בערך, בתור המאפיין gd:etag.

אם שירות תומך בגרסה 2, לכל פיד ואובייקט כניסה תהיה שיטת getEtag() לאחזור הערך של ה-ETag.

לקוח JavaScript תומך בשתי שיטות להכללת ETags בבקשה. הראשון הוא האובייקט opt_params החדש. לכל הפונקציות get/update/insert בגרסה 2 של ספריית הלקוח יש פרמטר opt_params חדש. אובייקט זה משמש לציון פרמטרים אופציונליים בעת שליחת בקשה. בשלב זה, 'etag' הוא הפרמטר האופציונלי היחיד הנתמך (אם כי ייתכן שפרמטרים נוספים ייתווספו בעתיד). לדוגמה, אפשר להוסיף ETag לבקשת GET כמו זו:

var opt_params = {};
opt_params['etag'] = 'ETAG GOES HERE';
service.getFeed(uri, successHandler, errorHandler, opt_params);

אפשר גם להוסיף תג ETag ישירות לפיד או לאובייקט הכניסה. לשם כך יש להפעיל את השיטה setEtag() בפיד או בכניסה.

מידע נוסף על ETags זמין בחומר העזר בנושא פרוטוקול GData.

שימוש ב-ETags לאחזור נתונים

ETags יכולים לעזור בצמצום רוחב הפס וזמן הביצוע בעת אחזור נתונים. תג ETag עשוי להיכלל בבקשת GET עם If-None-Match header:

If-None-Match: ETAG GOES HERE

אם ה-ETag תואם לגרסה הנוכחית של הפיד או של הרשומה, השרת מגיב בתגובה 304 NOT MODIFIED וגוף ריק. אחרת, השרת מגיב בתגובת 200 OK ובנתוני הפיד או הרשומה.

ניתן להשתמש ב-ETags בלקוח ה-JavaScript על ידי הוספת פרמטר 'etag' כששולחים את הבקשה:

var etag = feed.getEtag(); // Feed loaded from a previous request
var opt_params = {};
opt_params['etag'] = etag;
service.getFeed(feedUrl, successHandler, errorHandler, opt_params);

אחזורים מותנים פועלים גם עם ETags חזקים וגם חלשים. אם ה-ETag תואם, המערכת תקרא ל-handler של השגיאה עם תגובה 304:

function successHandler(feedRoot) {
  // 200 response
  // Update UI to display updates
}

function errorHandler(errorObj) {
  if (errorObj.cause.getStatus() == 304) {
    // 304 response, do nothing
  }
  // otherwise the response is some other error
}

כדי לראות דוגמה מעשית יותר של שימוש ב-ETags ב-JavaScript לדוגמה, כדאי להשתמש בדגימה של אחזור מותנה. הדוגמה הזו סוקרת את Blogger במרווחי זמן של 5 שניות המחפשת עדכונים בבלוג שלך. כאשר יש שינויים, הדוגמה מעדכנת רשימת פוסטים.

שימוש ב-ETags לעדכון ולמחיקה של נתונים

השימוש ב-ETags בבקשות לעדכון/מחיקה כדי להבטיח שלקוחות מרובים לא יחליפו בטעות זה את זה. במקרה כזה, ה-ETag כלול בכותרת If-Match:

If-Match: ETAG GOES HERE

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

במקרים מסוימים, ייתכן שתרצו לאלץ את השינויים בפועל, ללא קשר לשינויים אחרים בערך. כדי לעשות זאת, מעבירים את ה* לכותרת ה-If-Match:

If-Match: *

חשוב לזכור שפעולה זו תבטל שינויים שבוצעו על ידי לקוחות אחרים, ולכן חשוב להפעיל שיקול דעת.

ניתן לעדכן/למחוק רשומה רק באמצעות ETag חזק. ציון ETag חלש יוביל לשגיאה. כדי להגן על המידע הזה, לקוח JavaScript לא יגדיר תגים ETag חלשים בבקשות לעדכון ולמחיקה.

תגי ETag משמשים באותו אופן כמו אחזורים מותנים:

function updateData(entry, service) {
  var etag = entry.getEtag();
  var opt_params = {};
  opt_params['etag'] = etag; // Or use '*' to force an update.
  service.updateEntry(successHandler, errorHandler, opt_params);
}

function successHandler(response) {
  // Successful update
}

function errorHandler(errorObj) {
  // ERROR - Update failed. Could be due to an ETag mismatch, but check the
  // error message to make sure. An ETag error will be in the format:
  // Mismatch: etags = ["Qnc-fTVSLyp7ImA9WxJbFEsDRAw."], version = [1249675665358000]
}

כשמבצעים עדכון, אפשר לציין ETag בשני מקומות:

ברשומה עצמה, באמצעות השיטות getEtag() ו-setEtag().
בכותרת, באמצעות האובייקט opt_params (כפי שמוצג למעלה).

בשדה שנטען מבקשת GET קודמת כבר יוגדר שדה ETag. לכן, אם רוצים לציין את אותו ה-ETag באובייקט opt_params, אין צורך בכך. במקרה שבו ETag צוין גם בגוף הרשומה וגם ב-opt_params, ה-ETag ב-opt_params יקבל עדיפות. זה יכול להיות קצת מבלבל, לכן אם נתקלת בבעיות עם עדכונים מותנים, כדאי לך לבדוק את ה-ETag גם ברשומה וגם באובייקט opt_params.

כדי להקל עליך, לכיתות google.gdata.Entry יש שיטות משלהן לupdateEntry() ולdeleteEntry(). אם כבר קיים תג ETag בכיתה, אין צורך להוסיף אותו לבקשה. ספריית הלקוח תבצע את הפעולה הזו באופן אוטומטי. למשל:

// entry was loaded from a previous request.  No need to specify
// an ETag in opt_params here, it is added automatically.
entry.deleteEntry(successHandler, errorHandler);

השימוש ב-ETags יועיל לך מבלי לדאוג אם תגדיר אותם בצורה נכונה. עם זאת, אם רוצים לכפות את העדכון באמצעות '*', צריך לכלול תמיד את האובייקט opt_params עם 'etag' = '*'.

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

קטעים לדוגמה

אחזור מותנה ב-Blogger – עריכת סקרים ב-Blogger כל 5 שניות וחיפוש עדכונים.
עדכון מותנה באנשי קשר - מציג שתי מסגרות iframe נפרדות עם נתוני אנשי קשר, כך שניתן ליצור מחדש את האינטראקציה בין שני לקוחות במהלך יצירה/עדכון/מחיקה של אנשי קשר.

מקורות מידע

חזרה למעלה