מדריך ל-Python

חשוב: המסמך הזה נכתב לפני 2012. אפשרויות האימות שמתוארים במסמך זה (OAuth 1.0, AuthSub, ו-ClientLogin) הוצא משימוש באופן רשמי החל מ-20 באפריל 2012 והן אינן זמינות יותר. מומלץ לעבור אל OAuth 2.0 בהקדם האפשרי.

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

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

קהל

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

תחילת העבודה

כדי להשתמש בספריית הלקוח של Python, נדרשים Python 2.2 ואילך ואת המודולים המפורטים בדף ה-wiki של DependencyModules. אחרי הורדת ספריית הלקוח, לקבלת עזרה בהתקנת הלקוח ובשימוש בו, ראו תחילת העבודה עם ספריית Python בנתוני Google.

הרצת הדוגמה

דגימת פעילות מלאה נמצאת בספריית המשנה samples/sites של מאגר Mercurial של הפרויקט (/samples/sites/sites_example.py).

מריצים את הדוגמה כך:

python sites_example.py
# or
python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]

אם לא יסופקו הדגלים הנדרשים, האפליקציה תבקש מכם להזין את הערכים האלה. הדוגמה מאפשרת למשתמש לבצע מספר פעולות להדגים איך להשתמש בגרסה הקלאסית של Google Sites API. לכן יידרש אימות כדי לבצע פעולות מסוימות (למשל שינוי תוכן). התוכנית גם תבקש לבצע אימות באמצעות AuthSub, OAuth או ClientLogin.

כדי לכלול את הדוגמאות שבמדריך הזה בקוד שלכם, צריך את הצהרות הimport הבאות:

import atom.data
import gdata.sites.client
import gdata.sites.data

צריך גם להגדיר אובייקט SitesClient, שמייצג חיבור לקוח לגרסה הקלאסית של Google Sites API. מעבירים את שם האפליקציה ואת שם מרחב האינטרנט של האתר (מכתובת ה-URL שלו):

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')

כדי לעבוד עם אתר שמתארח בדומיין של G Suite, צריך להגדיר את הדומיין באמצעות הפרמטר domain:

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')

בקטעי הקוד שלמעלה, הארגומנט source הוא אופציונלי, אבל מומלץ למטרות רישום ביומן. היא צריכה בפורמט: company-applicationname-version

הערה: שאר המדריך מניח שיצרתם אובייקט SitesClient במשתנה client.

אימות לגרסה הקלאסית של Google Sites API

אפשר להשתמש בספריית הלקוח של Python כדי לעבוד עם פידים ציבוריים או פרטיים. Google Sites Data API מאפשר גישה לחשבונות פרטיים וציבוריים בהתאם להרשאות של אתר ולפעולה שאתם מנסים לבצע. לדוגמה, ייתכן שתהיה לך אפשרות לקרוא את פיד התוכן של אתר ציבורי אך לא לבצע בו עדכונים, משהו שדורש לקוח מאומת. כדי לעשות זאת, אפשר אימות שם משתמש/סיסמה של ClientLogin, או AuthSub OAuth.

למידע נוסף על AuthSub, OAuth ו-ClientLogin, ניתן לעיין בסקירה הכללית על אימות של ממשקי API של נתונים ב-Google.

AuthSub לאפליקציות אינטרנט

יש להשתמש באימות AuthSub לאפליקציות אינטרנט באפליקציות לקוח שצריכות לאמת את המשתמשים שלהם מול חשבונות Google או G Suite. המפעיל לא זקוק לגישה לשם המשתמש ולסיסמה של משתמש Google Sites - אלא רק נדרש אסימון AuthSub.

import gdata.gauth

def GetAuthSubUrl():
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session)

print '<a href="%s">Login to your Google account</a>' % GetAuthSubUrl()

def GetAuthSubUrl():
  domain = 'example.com'
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session, domain=domain)

OAuth לאפליקציות לאינטרנט או לאפליקציות מותקנות/לנייד

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

ClientLogin לאפליקציות מותקנות/לנייד

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

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1')
client.ClientLogin('user@gmail.com', 'pa$$word', client.source);

חזרה למעלה

עדכון אתר

אפשר להשתמש בפיד האתר כדי להציג רשימה של אתרים ב-Google Sites שבבעלות המשתמש או שיש לו הרשאות צפייה. אפשר להשתמש בו גם כדי לשנות את השם של אתר קיים. לסיום, בדומיינים של G Suite, אפשר להשתמש בהם גם כדי ליצור ו/או להעתיק באתר כולו.

הצגת אתרים

כדי להציג את רשימת האתרים שלמשתמש יש גישה אליהם, צריך להשתמש בשיטת GetSiteFeed() של הלקוח. השיטה כוללת הארגומנט uri, שבו ניתן להשתמש כדי לציין URI חלופי של פיד אתר. כברירת מחדל, GetSiteFeed() משתמש בשם האתר ובדומיין שהוגדר באובייקט הלקוח. אפשר לעיין בקטע תחילת העבודה כדי מידע נוסף על הגדרת הערכים האלה באובייקט הלקוח.

הנה דוגמה לאחזור רשימת האתרים של המשתמש המאומת:

feed = client.GetSiteFeed()

for entry in feed.entry:
  print '%s (%s)' % (entry.title.text, entry.site_name.text)
  if entry.summary.text:
    print 'description: ' + entry.summary.text
  if entry.FindSourceLink():
    print 'this site was copied from site: ' + entry.FindSourceLink()
  print 'acl feed: %s\n' % entry.FindAclLink()
  print 'theme: ' + entry.theme.text

קטע הקוד שלמעלה מדפיס את הכותרת של האתר, שם האתר, האתר שממנו הוא הועתק ו-URI של פיד ה-acl שלו.

יצירת אתרים חדשים

הערה: התכונה הזו זמינה רק לדומיינים ב-G Suite.

אפשר להקצות אתרים חדשים על ידי קריאה ל-method של CreateSite() של הספרייה. בדומה לעוזר הדיגיטלי של GetSiteFeed(), גם CreateSite() מקבל/ת הארגומנט האופציונלי, uri, שבו ניתן להשתמש כדי לציין URI חלופי של פיד אתר (במקרה של יצירת האתר תחת דומיין אחר מזה שמוגדר באובייקט SitesClient).

הנה דוגמה ליצירת אתר חדש עם הנושא 'צפחה'. ומספקת כותרת ותיאור (אופציונלי) (אופציונלי):

client.domain = 'example2.com'  # demonstrates creating a site under a different domain.

entry = client.CreateSite('Title For My Site', description='Site to hold precious memories', theme='slate')
print 'Site created! View it at: ' + entry.GetAlternateLink().href

הבקשה שלמעלה תוביל ליצירת אתר חדש בדומיין G Suite example2.com. במקרה כזה, כתובת ה-URL של האתר תהיה https://sites.google.com/a/example2.com/title-for-my-site.

אם האתר נוצר בהצלחה, השרת יגיב באמצעות gdata.sites.data.SiteEntry אובייקט, שמאוכלס ברכיבים שנוספו על ידי השרת: קישור לאתר, קישור לעדכון ה-ACL של האתר שם האתר, הכותרת, הסיכום וכן הלאה.

העתקת אתר

הערה: התכונה הזו זמינה רק לדומיינים ב-G Suite.

אפשר להשתמש ב-CreateSite() גם כדי להעתיק אתר קיים. כדי לעשות זאת, מעבירים את הארגומנט source_site של מילת המפתח. הקישור הזה יהיה זמין לכל אתר שיועתק דרך entry.FindSourceLink(). כאן יש דוגמה לשכפול של האתר נוצר בקטע יצירת אתרים חדשים:

copied_site = client.CreateSite('Copy of Title For My Site', description='My Copy', source_site=entry.FindSourceLink())
print 'Site copied! View it at: ' + copied_site.GetAlternateLink().href

נקודות חשובות:

• ניתן להעתיק רק אתרים ותבניות אתר שבבעלות המשתמש המאומת.
• אפשר גם להעתיק תבנית אתר. אתר הוא תבנית אם האפשרות 'פרסום אתר זה כתבנית' מסומנת בדף ההגדרות של 'Google Sites'.
• אתם יכולים להעתיק אתר מדומיין אחר, בתנאי שתירשמו כבעלים באתר המקור.

עדכון מטא-נתונים של אתר

כדי לעדכן את השם או את הסיכום של אתר, יש צורך בקובץ SiteEntry שכולל את האתר הרלוונטי. הזה בדוגמה משתמשת בשיטה GetEntry() כדי לאחזר קודם את SiteEntry, ולאחר מכן משנים את הכותרת, התיאור ותג הקטגוריה שלו:

uri = 'https://sites.google.com/feeds/site/example2.com/title-for-my-site'
site_entry = client.GetEntry(uri, desired_class=gdata.sites.data.SiteEntry)

site_entry.title.text = 'Better Title'
site_entry.summary.text = 'Better Description'
category_name = 'My Category'
category = atom.data.Category(
    scheme=gdata.sites.data.TAG_KIND_TERM,
    term=category_name)
site_entry.category.append(category)
updated_site_entry = client.Update(site_entry)

# To force the update, even if you do not have the latest changes to the entry:
# updated_site_entry = client.Update(site_entry, force=True)

חזרה למעלה

אחזור פיד הפעילות

הערה: כדי לגשת אל הפיד הזה, אתם צריכים להיות שותפי עריכה או בעלים של האתר. הלקוח שלך חייב לבצע אימות באמצעות אסימון AuthSub , OAuth או ClientLogin. למידע נוסף, ניתן לעיין בקטע אימות מול שירות Google Sites.

ניתן לאחזר את הפעילות האחרונה של אתר (שינויים) על ידי אחזור פיד הפעילות. השיטה GetActivityFeed() של lib מספקת גישה לפיד הזה:

print "Fetching activity feed of '%s'...\n" % client.site
feed = client.GetActivityFeed()

for entry in feed.entry:
  print '%s [%s on %s]' % (entry.title.text, entry.Kind(), entry.updated.text)

קריאה אל GetActivityFeed() מחזירה אובייקט gdata.sites.data.ActivityFeed שמכיל רשימה של gdata.sites.data.ActivityEntry. כל רשומה של פעילות מכילה מידע על שינוי שבוצע באתר.

חזרה למעלה

מאחזר היסטוריית גרסאות

הערה: כדי לגשת אל הפיד הזה, אתם צריכים להיות שותפי עריכה או בעלים של האתר. הלקוח שלך חייב לבצע אימות באמצעות אסימון AuthSub , OAuth או ClientLogin. למידע נוסף, ניתן לעיין בקטע אימות מול שירות Google Sites.

פיד הגרסאות מספק מידע על היסטוריית הגרסאות של כל רשומת תוכן. GetRevisionFeed() ניתן להשתמש ב-method כדי לאחזר את התיקונים של רשומת תוכן נתונה. השיטה כוללת ערך אופציונלי של uri פרמטר שמקבל gdata.sites.data.ContentEntry, URI מלא של רשומת תוכן או מזהה רשומת תוכן.

בדוגמה הבאה נשלחת שאילתה אל פיד התוכן, ומאחזרת את פיד הגרסאות של רשומת התוכן הראשונה:

print "Fetching content feed of '%s'...\n" % client.site
content_feed = client.GetContentFeed()
content_entry = content_feed.entry[0]

print "Fetching revision feed of '%s'...\n" % content_entry.title.text
revision_feed = client.GetRevisionFeed(content_entry)

for entry in revision_feed.entry:
  print entry.title.text
  print ' new version on:\t%s' % entry.updated.text
  print ' view changes:\t%s' % entry.GetAlternateLink().href
  print ' current version:\t%s...\n' % str(entry.content.html)[0:100]

קריאה אל GetRevisionFeed() מחזירה אובייקט gdata.sites.data.RevisionFeed שמכיל רשימה של gdata.sites.data.RevisionEntry. כל רשומה של גרסה קודמת מכילה מידע כמו התוכן בגרסה הקודמת, במספר הגרסה ובמועד יצירת הגרסה החדשה.

חזרה למעלה

פיד תוכן

אחזור פיד התוכן

הערה: פיד התוכן לא בהכרח מחייב אימות. בהתאם להרשאות השיתוף של האתר. אם האתר אינו ציבורי, הלקוח שלך חייב לבצע אימות באמצעות אסימון AuthSub , OAuth או ClientLogin. צפייה אימות מול שירות Google Sites.

פיד התוכן מחזיר את התוכן העדכני ביותר של אתר. אפשר לגשת ל-lib השיטה GetContentFeed(), שלוקחת פרמטר אופציונלי של מחרוזת uri כדי להעביר שאילתה מותאמת אישית.

הנה דוגמה לאחזור פיד התוכן כולו ולהדפסת כמה רכיבים מעניינים:

print "Fetching content feed of '%s'...\n" % client.site
feed = client.GetContentFeed()

for entry in feed.entry:
  print '%s [%s]' % (entry.title.text, entry.Kind())

  # Common properties of all entry kinds.
  print ' content entry id: ' + entry.GetNodeId()
  print ' revision:\t%s' % entry.revision.text
  print ' updated:\t%s' % entry.updated.text

  if entry.page_name:
    print ' page name:\t%s' % entry.page_name.text

  if entry.content:
    print ' content\t%s...' % str(entry.content.html)[0:100]

  # Subpages/items will have a parent link.
  parent_link = entry.FindParentLink()
  if parent_link:
    print ' parent link:\t%s' % parent_link

  # The alternate link is the URL pointing to Google Sites.
  if entry.GetAlternateLink():
    print ' view in Sites:\t%s' % entry.GetAlternateLink().href

  # If this entry is a filecabinet, announcementpage, etc., it will have a feed of children.
  if entry.feed_link:
    print ' feed of items:\t%s' % entry.feed_link.href

  print

טיפ: אפשר להשתמש בentry.Kind() כדי לקבוע את סוג הרשומה.

האובייקט feed שמתקבל הוא gdata.sites.data.ContentFeed שמכיל רשימה מתוך gdata.sites.data.ContentEntry. כל רשומה מייצגת דף/פריט שונה בתוך האתר של המשתמש וכולל רכיבים ספציפיים לסוג הרשומה שבו הוא נמצא. אפשר לעיין באפליקציה לדוגמה כדי לקבל רעיון טוב יותר חלק מהמאפיינים הזמינים בכל סוג של רשומה.

חזרה למעלה

דוגמאות לשאילתות של פיד תוכן

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

הערה: הדוגמאות בקטע הזה מתבססות על שיטת העזרה gdata.sites.client.MakeContentFeedUri() לבניית ה-URI הבסיסי של פיד התוכן.

אחזור סוגים ספציפיים של רשומות

כדי לאחזר רק סוג מסוים של רשומה, צריך להשתמש בפרמטר kind. לדוגמה, קטע הקוד הזה מחזיר רק attachment רשומות:

kind = 'webpage'

print 'Fetching only %s entries' % kind
uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind)
feed = client.GetContentFeed(uri=uri)

כדי להחזיר יותר מסוג אחד, צריך להפריד בין הפרמטרים kind באמצעות פסיק. לדוגמה, קטע הקוד הזה מחזיר filecabinet listpage ערכים:

kind = ','.join(['filecabinet', 'listpage'])

print 'Fetching only %s entries' % kind
uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind)
feed = client.GetContentFeed(uri=uri)

אחזור דף לפי נתיב

אם אתם יודעים את הנתיב היחסי של דף באתר שנוצר באמצעות Google Sites, אתם יכולים להשתמש בפרמטר path כדי לאחזר את הדף הספציפי הזה. בדוגמה הזו תוחזר הדף שנמצא ב- http://sites.google.com/domainName/siteName/path/to/the/page:

path = '/path/to/the/page'

print 'Fetching page by its path: ' + path
uri = '%s?path=%s' % (client.MakeContentFeedUri(), path)
feed = client.GetContentFeed(uri=uri)

אחזור כל הרשומות בדף הורה

אם אתם יודעים מהו מזהה רשומת התוכן של דף כלשהו (למשל, '1234567890' בדוגמה הבאה), תוכלו להשתמש בפרמטר parent. כדי לאחזר את כל רשומות הצאצא שלו (אם יש):

parent = '1234567890'

print 'Fetching all children of parent entry: ' + parent
uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent)
feed = client.GetContentFeed(uri=uri)

פרמטרים נוספים זמינים במדריך העזר.

חזרה למעלה

יצירת תוכן

הערה: לפני שיוצרים תוכן לאתר, צריך לוודא שהגדרתם את האתר באפליקציית הלקוח.
client.site = "siteName"

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

רשימה של סוגי הצמתים הנתמכים זמינה בפרמטר kind במדריך העזר.

יצירת פריטים / דפים חדשים

בדוגמה הזו נוצר webpage חדש ברמה העליונה, כולל XHTML עבור גוף הדף, ומגדיר את כותרת הכותרת 'New WebPage Title':

entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>')
print 'Created. View it at: %s' % entry.GetAlternateLink().href

אם הבקשה תתבצע בהצלחה, entry יכיל עותק של הרשומה שנוצרה בשרת, בתור gdata.sites.gdata.ContentEntry.

כדי ליצור רשומות מורכבות יותר שמאוכלסות בתהליך היצירה (למשל listpage עם כותרות של עמודות), צריך ליצור gdata.sites.data.ContentEntry, ממלאים את המאפיינים הרצויים וקוראים לפונקציה client.Post().

יצירת פריטים או דפים בנתיבים של כתובות URL מותאמות אישית

כברירת מחדל, הדוגמה הקודמת תיווצר מתחת לכתובת ה-URL http://sites.google.com/domainName/siteName/new-webpage-title והקבוצה לקבל את הכותרת 'כותרת חדשה של דף אינטרנט'. כלומר, הכותרת מנורמלת ל-new-webpage-title עבור כתובת ה-URL. כדי להתאים אישית את נתיב כתובת ה-URL של דף, אפשר להגדיר את המאפיין page_name ברשומת התוכן. העוזר הדיגיטלי של CreatePage() מספקת אותו כארגומנט אופציונלי של מילת מפתח.

בדוגמה הזו נוצר דף filecabinet חדש עם הכותרת 'File Storage', אבל הדף נוצר. מתחת לכתובת ה-URL http://sites.google.com/domainName/siteName/files (במקום http://sites.google.com/domainName/siteName/file-storage) באמצעות ציון המאפיין page_name.

entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files')
print 'Created. View it at: ' + entry.GetAlternateLink().href

השרת משתמש בכללי הקדימות הבאים כדי לתת שם לנתיב כתובת ה-URL של דף:

1. page_name, אם קיים. חייב לעמוד בדרישות של a-z, A-Z, 0-9, -, _.
2. title, לא יכול להיות null אם שם הדף לא קיים. נירמול הוא לחתוך + לכווץ רווחים לבנים ל-'-' וגם צריך להסיר את התווים שלא תואמים ל-a-z, A-Z, 0-9, -, _.

יצירת דפי משנה

כדי ליצור דפי משנה (ילדים) בדף הורה, צריך להשתמש בארגומנט parent של מילת המפתח של CreatePage(). הערך parent יכול להיות gdata.sites.gdata.ContentEntry או מחרוזת שמייצגת את המזהה העצמי המלא של רשומת התוכן.

בדוגמה הזו נשלחת שאילתה אל פיד התוכן עבור announcementpage ויוצרת announcement חדש מתחת לתג הראשון שנמצא:

uri = '%s?kind=%s' % (client.MakeContentFeedUri(), 'announcementpage')
feed = client.GetContentFeed(uri=uri)

entry = client.CreatePage('announcement', 'Party!!', html='My place, this weekend', parent=feed.entry[0])
print 'Posted!'

העלאת קבצים

בדיוק כמו ב-Google Sites, ה-API תומך בהעלאות של קבצים מצורפים לדף של ספריית קבצים או לדף הורה. צריך להעלות את הקבצים המצורפים לדף הורה. לכן, צריך להגדיר קישור הורה בקובץ ContentEntry שניסית להעלות. למידע נוסף, ראו יצירת דפי משנה.

השיטה UploadAttachment() של ספריית הלקוח מספקת את הממשק להעלאת קבצים מצורפים.

הקבצים מועלים

בדוגמה הזו קובץ PDF מועלה אל filecabinet הראשון שנמצא בפיד התוכן של המשתמש. הקובץ המצורף נוצר עם הכותרת 'מדריך חדש לעובדים' ותיאור (אופציונלי) 'חבילת משאבי אנוש'.

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'filecabinet')
feed = client.GetContentFeed(uri=uri)

attachment = client.UploadAttachment('/path/to/file.pdf', feed.entry[0], content_type='application/pdf',
                                     title='New Employee Handbook', description='HR Packet')
print 'Uploaded. View it at: %s' % attachment.GetAlternateLink().href

אם ההעלאה תתבצע בהצלחה, attachment יכיל עותק של הקובץ המצורף שנוצר בשרת.

העלאת קובץ מצורף לתיקייה

תיקיות קבצים ב-Google Sites תומכות בתיקיות. מילת המפתח UploadAttachment() מספקת מילת מפתח נוספת ארגומנט, folder_name שבו אפשר להשתמש כדי להעלות קובץ מצורף לתיקייה filecabinet. פשוט מציינים את שם התיקייה:

import gdata.data

ms = gdata.data.MediaSource(file_path='/path/to/file.pdf', content_type='application/pdf')
attachment = client.UploadAttachment(ms, feed.entry[0], title='New Employee Handbook',
                                     description='HR Packet', folder_name='My Folder')

שימו לב שהדוגמה הזו מעבירה במקום זאת אובייקט gdata.data.MediaSource אל UploadAttachment() של נתיב קובץ. הוא גם לא מעביר סוג תוכן. במקום זאת, סוג התוכן מצוין באובייקט MediaSource.

קבצים מצורפים מהאינטרנט

קבצים מצורפים באינטרנט הם סוגים מיוחדים של קבצים מצורפים. למעשה, הם קישורים לקבצים אחרים באינטרנט שאפשר להוסיף לרישומים של filecabinet. התכונה הזו מקבילה להגדרה 'הוספת קובץ לפי כתובת URL' העלאה דרך ממשק המשתמש של Google Sites.

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

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

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'filecabinet')
feed = client.GetContentFeed(uri=uri)

parent_entry = feed.entry[0]
image_url = 'http://www.google.com/images/logo.gif'
web_attachment = client.CreateWebAttachment(image_url, 'image/gif', 'GoogleLogo',
                                            parent_entry, description='nice colors')

print 'Created!'

השיחה יוצרת קישור שמפנה לתמונה שבכתובת 'http://www.google.com/images/logo.gif' filecabinet.

חזרה למעלה

עדכון התוכן

עדכון מטא-נתונים ו/או תוכן HTML של דף

ניתן לערוך את המטא-נתונים (כותרת, שם הדף וכו') ואת תוכן הדף מכל סוג של רשומה על ידי באמצעות השיטה Update() של הלקוח.

דוגמה לעדכון של listpage עם השינויים הבאים:

• השם השתנה ל'כותרת מעודכנת'
• תוכן ה-HTML של הדף מעודכן ל'תוכן HTML מעודכן'
• הכותרת של העמודה הראשונה ברשימה תשתנה ל"בעלים"

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'listpage')
feed = client.GetContentFeed(uri=uri)

old_entry = feed.entry[0]

# Update the listpage's title, html content, and first column's name.
old_entry.title.text = 'Updated Title'
old_entry.content.html = 'Updated HTML Content'
old_entry.data.column[0].name = 'Owner'

# You can also change the page's webspace page name on an update.
# old_entry.page_name = 'new-page-path'

updated_entry = client.Update(old_entry)
print 'List page updated!'

החלפת התוכן והמטא-נתונים של קובץ מצורף

אפשר להחליף את התוכן של קובץ מצורף על ידי יצירת אובייקט MediaSource חדש עם תוכן הקובץ החדש וקריאה ל-method של Update() של הלקוח. של הקובץ המצורף אפשר גם לעדכן מטא-נתונים (כמו שם ותיאור), או רק את המטא-נתונים. הדוגמה הבאה ממחישה את עדכון התוכן והמטא-נתונים של קבצים בו-זמנית:

import gdata.data

# Load the replacement content in a MediaSource. Also change the attachment's title and description.
ms = gdata.data.MediaSource(file_path='/path/to/replacementContent.doc', content_type='application/msword')
existing_attachment.title.text = 'Updated Document Title'
existing_attachment.summary.text = 'version 2.0'

updated_attachment = client.Update(existing_attachment, media_source=ms)
print "Attachment '%s' changed to '%s'" % (existing_attachment.title.text, updated_attachment.title.text)

חזרה למעלה

מחיקת התוכן

כדי להסיר דף או פריט מאתר שנוצר באמצעות Google Sites, קודם מאחזרים את רשומת התוכן ואז מפעילים את השיטה Delete() של הלקוח.

client.Delete(content_entry)

אפשר גם להעביר את השיטה Delete() לקישור edit של רשומת התוכן ו/או לאלץ את המחיקה:

# force=True sets the If-Match: * header instead of using the entry's ETag.
client.Delete(content_entry.GetEditLink().href, force=True)

מידע נוסף על ETags זמין במדריך Google Data APIs.

חזרה למעלה

הורדת קבצים מצורפים

כל רשומה של attachment מכילה קישור לתוכן src שיכול לשמש להורדת תוכן הקובץ. לקוח Google Sites כולל שיטה עוזרת לגשת לקובץ ולהוריד אותו מהקישור הזה: DownloadAttachment(). המערכת מקבלת URI של gdata.sites.data.ContentEntry או מורידה URI לארגומנט הראשון, ונתיב קובץ לשמירת הקובץ המצורף לכיתוב השני.

הדוגמה הבאה מאחזרת רשומת קובץ מצורף מסוימת (על ידי שליחת שאילתה על הקישור self) ומורידה את הקובץ לנתיב שצוין:

uri = 'https://sites.google.com/feeds/content/site/siteName/1234567890'
attachment = client.GetEntry(uri, desired_class=gdata.sites.data.ContentEntry)

print "Downloading '%s', a %s file" % (attachment.title.text, attachment.content.type)
client.DownloadAttachment(attachment, '/path/to/save/test.pdf')

print 'Downloaded!'

מפתח האפליקציה צריך לציין סיומת קובץ שמתאימה לסוג התוכן של הקובץ המצורף. סוג התוכן אפשר למצוא את זה ב-entry.content.type.

במקרים מסוימים ייתכן שלא ניתן יהיה להוריד את הקובץ לדיסק (למשל, אם האפליקציה פועלת ב-Google App Engine). במצבים כאלה, צריך להשתמש ב-_GetFileContent() כדי לאחזר את תוכן הקובץ ולאחסן אותו בזיכרון.

ההורדה לדוגמה הזו היא קובץ מצורף לזיכרון.

try:
  file_contents = client._GetFileContent(attachment.content.src)
  # TODO: Do something with the file contents
except gdata.client.RequestError, e:
  raise e

חזרה למעלה

פיד ACL

סקירה כללית של הרשאות שיתוף (ACL)

כל רשומת ACL בפיד ה-ACL מייצגת תפקיד גישה של ישות מסוימת: משתמש, קבוצת משתמשים, דומיין, או גישת ברירת המחדל (שהיא אתר ציבורי). הרשומות יוצגו רק לישויות עם גישה מפורשת – תוצג רשומה אחת לכל כתובת אימייל בקטע "אנשים שיש להם גישה" במסך השיתוף של ממשק המשתמש של Google Sites. כך, מנהלי דומיינים לא יוצגו למרות שיש להם גישה מרומזת לאתר.

תפקידים

רכיב התפקיד מייצג רמת גישה שיכולה להיות לישות. יש ארבעה ערכים אפשריים לאלמנט gAcl:role:

• Reader – צופה (שווה להרשאת קריאה בלבד).
• author – שותף עריכה (מקביל לגישת קריאה/כתיבה).
• owner — בדרך כלל האדמין של האתר (מקביל לגישת קריאה/כתיבה).

טווחים

רכיב ההיקף מייצג את הישות עם רמת הגישה הזו. יש ארבעה סוגים אפשריים של הרכיב gAcl:scope:

• user – ערך של כתובת אימייל, למשל user@gmail.com.
• group — כתובת אימייל של קבוצה ב-Google, כמו "group@domain.com".
• domain — שם דומיין ב-G Suite, לדוגמה 'domain.com'.
• default – יש רק היקף אפשרי אחד מסוג 'default', שאין לו ערך (למשל <gAcl:scope type="default">). ההיקף הספציפי הזה שולט בגישה של כל משתמש כברירת מחדל באתר ציבורי.

הערה: לדומיינים לא יכול להיות ערך gAcl:role מוגדר כ'בעלים' הם יכולים להיות רק קוראים או כותבים.

אחזור פיד ה-ACL

ניתן להשתמש בפיד ה-ACL כדי לשלוט בהרשאות השיתוף של אתר, ולאחזר אותו באמצעות השיטה GetAclFeed().

הדוגמה הבאה מאחזרת את פיד ה-ACL של האתר שמוגדר כרגע באובייקט SitesClient, ומדפיסה את הרשומות של ההרשאות:

print "Fetching acl permissions of site '%s'...\n" % client.site

feed = client.GetAclFeed()
for entry in feed.entry:
  print '%s (%s) - %s' % (entry.scope.value, entry.scope.type, entry.role.value)

אחרי שאילתה שבוצעה בהצלחה, feed יהיה אובייקט gdata.sites.data.AclFeed שמכיל רשימה של gdata.sites.data.AclEntry.

אם עובדים עם רשומות ב-SiteFeed, כל SiteEntry מכיל קישור לפיד ה-ACL שלו. לדוגמה, קטע הקוד הבא מאחזר את האתר הראשון בפיד האתר של המשתמש ושולח שאילתה על פיד ה-ACL שלו:

feed = client.GetSiteFeed()
site_entry = feed.entry[0]

print "Fetching acl permissions of site '%s'...\n" % site_entry.site_name.text
feed = client.GetAclFeed(uri=site_entry.FindAclLink())

שיתוף אתר

הערה: ייתכן שתוכלו לשתף רשימות ACL מסוימות רק אם הדומיין מוגדר. כדי לאפשר הרשאות כאלה (למשל, אם מופעל שיתוף עם גורמים מחוץ לדומיין עבור דומיינים של G Suite וכו').

כדי לשתף אתר שנוצר באמצעות Google Sites באמצעות ה-API, צריך ליצור gdata.sites.gdata.AclEntry עם gdata.acl.data.AclScope ו-gdata.acl.data.AclRole. לצפייה הקטע סקירה כללית של פיד ACL עבור AclScope ו-AclRoles.

הדוגמה הבאה מעניקה הרשאות קריאה באתר למשתמש 'user@example.com':

import gdata.acl.data

scope = gdata.acl.data.AclScope(value='user@example.com', type='user')
role = gdata.acl.data.AclRole(value='reader')
acl = gdata.sites.gdata.AclEntry(scope=scope, role=role)

acl_entry = client.Post(acl, client.MakeAclFeedUri())
print "%s %s added as a %s" % (acl_entry.scope.type, acl_entry.scope.value, acl_entry.role.value)

שיתוף ברמת הקבוצה והדומיין

בדומה לשיתוף אתר עם משתמש יחיד, אפשר לשתף אתר בכל קבוצת Google או דומיין G Suite. הערכים הנדרשים של scope מפורטים בהמשך.

שיתוף עם כתובת אימייל של קבוצה:

scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')

שיתוף עם דומיין שלם:

scope = gdata.acl.data.AclScope(value='example.com', type='domain')

שיתוף ברמת הדומיין נתמך רק בדומיינים של G Suite, ורק בדומיין שבו האתר מתארח. לדוגמה, http://sites.google.com/a/domain1.com/siteA יכול לשתף רק את האתר כולו עם domain1.com ולא עם domain2.com. אתרים לא מתארחים בדומיין של G Suite (למשל, http://sites.google.com/site/siteB) לא יכולים להזמין דומיינים.

שינוי הרשאות שיתוף

להרשאת שיתוף קיימת באתר, קודם צריך לאחזר את AclEntry הרלוונטי ולשנות את ההרשאה ולאחר מכן לקרוא ל-method של Update() של הלקוח כדי לשנות את ה-ACL בשרת.

הדוגמה הזו משנה את הacl_entry הקודמת שלנו בקטע שיתוף אתר, על ידי עדכון 'user@example.com' להיות כותב (שותף עריכה):

acl_entry.role.value = 'writer'
updated_acl = client.Update(acl_entry)

# To force the update, even if you do not have the latest changes to the entry:
# updated_acl = client.Update(acl_entrys, force=True)

מידע נוסף על ETags זמין במדריך Google Data APIs.

המערכת מסירה את הרשאות השיתוף

כדי להסיר הרשאת שיתוף, קודם צריך לאחזר את AclEntry ואז להפעיל את השיטה Delete() של הלקוח.

client.Delete(acl_entry)

אפשר גם להעביר ל-method Delete() את הקישור edit של רשומת ה-ACL ו/או לאלץ את המחיקה:

# force=True sets the If-Match: * header instead of using the entry's ETag.
client.Delete(acl_entry.GetEditLink().href, force=True)

מידע נוסף על ETags זמין במדריך Google Data APIs.

חזרה למעלה

נושאים מיוחדים

אחזור חוזר של פיד או רשומה

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

כדי לבצע אחזור מותנה מהסוג הזה, צריך להעביר ערך ETag אל GetEntry(). לדוגמה, אם היה לכם אובייקט entry קיים:

import gdata.client

try:
  entry = client.GetEntry(entry.GetSelfLink().href, desired_class=gdata.sites.data.ContentEntry, etag=entry.etag)
except gdata.client.NotModified, error:
  print 'You have the latest copy of this entry'
  print error

אם GetEntry() מוסיף את החריג gdata.client.NotModified, הערך ETag תואם לגרסה בשרת, כלומר יש לך את העותק העדכני ביותר. עם זאת, אם לקוח/משתמש אחר ביצע שינויים, הרשומה החדשה תוחזר ב-entry ולא תתבצע החרגה כלשהי.

מידע נוסף על ETags זמין במדריך Google Data APIs.

חזרה למעלה