מדריך ל-Python

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

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

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

קהל

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

תחילת העבודה

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

הרצת הדוגמה

דגימת פעילות מלאה נמצאת בספריית המשנה 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]

אם לא תספקו את הדגלים הנדרשים, האפליקציה תבקש מכם להזין את הערכים האלה. הדוגמה מאפשרת למשתמש לבצע מספר פעולות שממחישות איך משתמשים ב-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 כדי לעבוד עם פידים ציבוריים או פרטיים. באמצעות 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 אפשר להשתמש בו גם כדי ליצור או להעתיק אתר שלם.

הצגת אתרים

כדי לקבל רשימה של האתרים שיש למשתמש גישה אליהם, משתמשים ב-method ‏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.

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

דוגמה ליצירת אתר חדש עם העיצוב 'slate', עם כותרת ותיאור (אופציונלי):

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. אימות לשירות 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. אימות לשירות Sites

פיד הגרסאות מספק מידע על היסטוריית הגרסאות של כל רשומת תוכן. אפשר להשתמש ב-method‏ 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. אימות לשירות Sites

פיד התוכן מחזיר את התוכן העדכני ביותר באתר. כדי לגשת אליו, שולחים קריאה ל-method GetContentFeed() של lib, שלוקחת פרמטר מחרוזת 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 ופרמטרים ספציפיים ל-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, תוכלו להשתמש בפרמטר 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'. כלומר, הכותרת מתאמת ל-new-webpage-title בכתובת ה-URL. כדי להתאים אישית את נתיב כתובת ה-URL של דף, אפשר להגדיר את המאפיין page_name ברשומת התוכן. כלי העזר CreatePage() מספק את הערך הזה כארגומנט אופציונלי של מילת מפתח.

בדוגמה הזו נוצר דף filecabinet חדש עם הכותרת 'אחסון קבצים', אבל הדף נוצר בכתובת ה-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' ו-'nice colors', בהתאמה.

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 של דף

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

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

• הכותרת תשתנה ל'Updated Title'
• תוכן ה-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 חדש עם תוכן הקובץ החדש ומפעילים את השיטה 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)

מידע נוסף על תגי ETag זמין במדריך העזרה של Google Data APIs.

חזרה למעלה

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

כל רשומה attachment מכילה קישור src לתוכן שאפשר להשתמש בו כדי להוריד את תוכן הקובץ. לקוח 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 – צופה (שווה להרשאת קריאה בלבד).
• writer – שותף עריכה (גישה לקריאה וכתיבה).
• 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)

מידע נוסף על תגי ETag זמין במדריך העזרה של Google Data APIs.

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

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

client.Delete(acl_entry)

אפשר גם להעביר לשיטה 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)

מידע נוסף על תגי ETag זמין במדריך העזרה של 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.

חזרה למעלה