راهنمای Python

مهم: این سند قبل‌از سال ۲۰۱۲ نوشته شده است. گزینه‌های اصالت‌سنجی شرح‌داده‌شده در این سند (OAuth 1.0،‏ AuthSub، و ClientLogin) از تاریخ ۲۰ آوریل ۲۰۱۲ رسمی منسوخ شده‌اند و دیگر دردسترس نیستند. توصیه می‌کنیم در اسرع وقت به OAuth 2.0 انتقال دهید.

«میانای برنامه‌سازی کاربردی داده‌های Google Sites» به برنامه‌های مشتری اجازه می‌دهد به محتوای سایت Google دسترسی داشته باشند، آن را منتشر کنند، و تغییر دهند. برنامه کلاینت شما همچنین می‌تواند فهرست فعالیت‌های اخیر را درخواست کند، سابقه بازبینی را واکشی کند، و پیوست‌ها را بارگیری کند.

این راهنما علاوه‌بر ارائه اطلاعاتی درباره قابلیت‌های Sites Data API، نمونه‌هایی از تعامل با API بااستفاده از کتابخانه مشتری Python ارائه می‌دهد. برای دریافت راهنمایی درباره راه‌اندازی کتابخانه کارخواه، به شروع به کار با کتابخانه کارخواه Google Data Python مراجعه کنید. اگر علاقه‌مندید درباره پروتکل زیربنایی که کتابخانه کارخواه Python برای تعامل با Sites API کلاسیک استفاده می‌کند بیشتر بدانید، لطفاً راهنمای پروتکل را ببینید.

مخاطبان

این سند برای توسعه‌دهندگانی درنظر گرفته شده است که می‌خواهند برنامه‌های کارخواه بنویسند که با «سایت‌های Google» بااستفاده از کتابخانه کارخواه Google Data Python تعامل داشته باشد.

درحال شروع کردن

برای استفاده از کتابخانه کارخواه Python، به Python 2.2+ و واحدهای فهرست‌شده در صفحه ویکی 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 راه‌اندازی کنید که نشان‌دهنده اتصال کارخواه به «میانای برنامه‌سازی کاربردی کلاسیک سایت‌ها» است. نام برنامه و نام فضای وب «سایت» (از نشانی وب آن) را ارسال کنید:

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 ایجاد کرده‌اید.

اصالت‌سنجی در «میانای برنامه‌سازی کاربردی کلاسیک سایت‌ها»

از کتابخانه کارخواه Python می‌توان برای کار با فیدهای عمومی یا خصوصی استفاده کرد. «میانای برنامه‌سازی کاربردی داده‌های سایت‌ها» بسته به اجازه‌های «سایت» و عملیاتی که می‌خواهید انجام دهید، دسترسی به فیدهای خصوصی و عمومی را فراهم می‌کند. برای مثال، ممکن است بتوانید فید محتوای «سایت» عمومی را بخوانید اما نتوانید آن را به‌روزرسانی کنید - این کار به مشتری اصیل‌سازی‌شده نیاز دارد. این کار را می‌توان ازطریق اصالت‌سنجی نام کاربری/گذرواژه ClientLogin، AuthSub، یا OAuth انجام داد.

لطفاً برای اطلاعات بیشتر درباره AuthSub،‏ OAuth، و ClientLogin، به نمای کلی اصالت‌سنجی Google Data APIs مراجعه کنید.

‫AuthSub برای برنامه‌های وب

برنامه‌های کارخواه که نیاز دارند کاربرانشان را در حساب‌های Google یا G Suite اصالت‌سنجی کنند باید از اصالت‌سنجی AuthSub برای برنامه‌های وب استفاده کنند. کاربر به دسترسی به نام کاربری و گذرواژه کاربر «سایت‌های Google» نیاز ندارد - فقط یک AuthSub token لازم است.

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» که کاربر مالک آن‌ها است یا اجازه مشاهده آن‌ها را دارد استفاده کرد. همچنین می‌توان از آن برای اصلاح نام سایت موجود استفاده کرد. درنهایت، برای دامنه‌های G Suite، می‌توان از آن برای ایجاد و/یا کپی کردن کل سایت نیز استفاده کرد.

فهرست کردن سایت‌ها

برای فهرست کردن سایت‌هایی که کاربر به آن‌ها دسترسی دارد، از روش GetSiteFeed() کارخواه استفاده کنید. این روش آرگومان اختیاری 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

گزیده بالا عنوان سایت، نام سایت، سایتی که از آن کپی شده است، و نشانی وب فید acl آن را چاپ می‌کند.

درحال ایجاد سایت‌های جدید

توجه: این ویژگی فقط برای دامنه‌های G Suite دردسترس است.

سایت‌های جدید را می‌توان با فراخوانی روش CreateSite() کتابخانه آماده کرد. مشابه با عنصر کمکی GetSiteFeed()، عنصر CreateSite() نیز آرگومان اختیاری 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 ایجاد می‌کند. بنابراین، نشانی وب سایت 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 اصالت‌سنجی کند. به اصالت‌سنجی در سرویس «سایت‌ها» مراجعه کنید.

با واکشی کردن فید فعالیت می‌توانید فعالیت اخیر (تغییرات) «سایت» را واکشی کنید. روش GetActivityFeed() کتابخانه دسترسی به این فید را فراهم می‌کند:

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 اصالت‌سنجی کند. به اصالت‌سنجی در سرویس «سایت‌ها» مراجعه کنید.

فید بازبینی اطلاعاتی درباره سابقه بازبینی برای هر ورودی محتوا ارائه می‌دهد. از روش GetRevisionFeed() می‌توان برای واکشی کردن ویرایش‌های یک ورودی محتوای معین استفاده کرد. این روش یک uri پارامتر اختیاری می‌گیرد که gdata.sites.data.ContentEntry، یک نشانی کامل از یک ورودی محتوا، یا یک شناسه ورودی محتوا را می‌پذیرد.

این مثال فید محتوا را پُرسمان می‌کند و فید بازبینی را برای اولین ورودی محتوا واکشی می‌کند:

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 اصالت‌سنجی کند. به اصالت‌سنجی در سرویس «سایت‌ها» مراجعه کنید.

فید محتوا جدیدترین محتوای «سایت» را برمی‌گرداند. با فراخوانی روش lib's 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 و پارامترهای مختص به Sites API کلاسیک جستجو کنید. برای اطلاعات دقیق‌تر و فهرست کامل پارامترهای پشتیبانی‌شده، به راهنمای مرجع مراجعه کنید.

توجه: مثال‌های این بخش از روش کمکی gdata.sites.client.MakeContentFeedUri() برای ساختن نشانی وب پایه فید محتوا استفاده می‌کنند.

درحال بازیابی انواع ورودی خاص

برای واکشی کردن فقط نوع خاصی از ورودی، از پارامتر 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)

درحال بازیابی همه ورودی‌های زیر صفحه اصلی

اگر شناسه ورودی محتوای صفحه‌ای را می‌دانید (مثلاً «۱۲۳۴۵۶۷۸۹۰» در مثال زیر)، می‌توانید از پارامتر 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 برای بدنه صفحه اضافه می‌کند، و عنوان سرصفحه را روی «عنوان صفحه وب جدید» تنظیم می‌کند:

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() را فراخوانی کنید.

ساختن عناصر/صفحه‌ها در مسیرهای نشانی وب سفارشی

به‌طور پیش‌فرض، مثال قبلی در نشانی وب http://sites.google.com/domainName/siteName/new-webpage-title ایجاد می‌شود و عنوان صفحه آن «عنوان صفحه وب جدید» خواهد بود. یعنی عنوان برای نشانی وب به new-webpage-title عادی‌سازی شده است. برای سفارشی‌سازی مسیر نشانی وب صفحه، می‌توانید دارایی page_name را در ورودی محتوا تنظیم کنید. یاری‌رسان CreatePage() این را به‌عنوان آرگومان کلیدواژه اختیاری ارائه می‌دهد.

این مثال صفحه filecabinet جدیدی با عنوان «ذخیره‌سازی فایل» ایجاد می‌کند، اما با مشخص کردن دارایی page_name، صفحه را در نشانی وب http://sites.google.com/domainName/siteName/files (به‌جای http://sites.google.com/domainName/siteName/file-storage) ایجاد می‌کند.

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

سرور از قوانین اولویت زیر برای نام‌گذاری مسیر نشانی وب صفحه استفاده می‌کند:

1. ‫page_name، درصورت وجود. باید a-z, A-Z, 0-9, -, _ را برآورده کند.
2. ‫title، اگر نام صفحه وجود ندارد نباید تهی باشد. عادی‌سازی یعنی حذف + جمع کردن فضای سفید به «-» و حذف نویسه‌هایی که با a-z, A-Z, 0-9, -, _ مطابقت ندارند.

درحال ایجاد زیرصفحه‌ها

برای ایجاد زیرصفحه (فرزند) در زیر صفحه والد، از آرگومان کلیدواژه CreatePage()parent استفاده کنید. parent می‌تواند هم gdata.sites.gdata.ContentEntry باشد و هم رشته‌ای که نشان‌دهنده شناسه خود کامل ورودی محتوا است.

این مثال فید محتوا را برای announcementpages پُرسمان می‌کند و 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» از پوشه‌ها پشتیبانی می‌کنند. 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 خود اضافه کنید. این ویژگی مشابه روش بارگذاری «افزودن فایل با نشانی وب» در واسط کاربر 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 صفحه

فراداده (عنوان، نام صفحه، و غیره) و محتوای صفحه هر نوع ورودی را می‌توان بااستفاده از روش 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 جدید با محتوای فایل جدید و فراخوانی روش 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»، ابتدا ورودی محتوا را بازیابی کنید، سپس روش Delete() مشتری را فراخوانی کنید.

client.Delete(content_entry)

همچنین می‌توانید پیوند edit ورودی محتوا را به روش Delete() منتقل کنید و/یا حذف را اجباری کنید:

# 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 است که می‌توان از آن برای بارگیری محتوای فایل استفاده کرد. کارخواه «سایت‌ها» حاوی روش کمکی برای دسترسی به فایل و بارگیری آن از این پیوند است: DownloadAttachment(). این دستور برای آرگومان اول خود gdata.sites.data.ContentEntry یا نشانی وب بارگیری را می‌پذیرد و برای آرگومان دوم، مسیر فایل را برای ذخیره پیوست می‌پذیرد.

این مثال ورودی پیوست خاصی را (با پُرسمان کردن 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 وجود دارد:

• خواننده — یک بیننده (معادل دسترسی فقط خواندنی).
• نویسنده — یک همیار (معادل دسترسی خواندن/نوشتن).
• مالک — معمولاً سرپرست سایت (معادل دسترسی خواندن/نوشتن).

دوربین تفنگ

عنصر محدوده نشان‌دهنده نهادی است که این سطح دسترسی را دارد. چهار نوع ممکن برای عنصر gAcl:scope وجود دارد:

• کاربر — مقدار نشانی ایمیل، برای نمونه «user@gmail.com».
• گروه — نشانی ایمیل «گروه Google»، برای نمونه «group@domain.com».
• دامنه — نام دامنه G Suite، برای نمونه «domain.com».
• پیش‌فرض — فقط یک محدوده ممکن از نوع «پیش‌فرض» وجود دارد که مقدار ندارد (برای نمونه <gAcl:scope type="default">). این محدوده خاص دسترسی را که هر کاربر به‌طور پیش‌فرض در سایت عمومی دارد کنترل می‌کند.

توجه: دامنه‌ها نمی‌توانند مقدار gAcl:role <0x0A> را روی دسترسی «مالک» تنظیم کنند، آن‌ها فقط می‌توانند خواننده یا نویسنده باشند.

درحال بازیابی فید 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 خود است. برای مثال، این گزیده اولین سایت را در «فید سایت» کاربر واکشی می‌کند و فید «فهرست کنترل دسترسی» آن را پُرسمان می‌کند:

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())

هم‌رسانی سایت

توجه: برخی‌از فهرست‌های کنترل دسترسی هم‌رسانی فقط درصورتی امکان‌پذیر است که دامنه برای اجازه دادن به چنین اجازه‌هایی پیکربندی شده باشد (برای نمونه، اگر هم‌رسانی خارج از دامنه برای دامنه‌های G Suite فعال باشد، و غیره).

برای هم‌رسانی کردن «سایت Google» بااستفاده از API، gdata.sites.gdata.AclEntry را با مقادیر gdata.acl.data.AclScope و gdata.acl.data.AclRole موردنظر ایجاد کنید. برای مقادیر احتمالی AclScope و AclRoles، به بخش نمای کلی فید ACL مراجعه کنید.

این مثال اجازه‌های خواندن را در «سایت» به کاربر «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 موردنظر را واکشی کنید، اجازه را به‌دلخواه تغییر دهید، و سپس روش 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)

همچنین می‌توانید پیوند edit ورودی فهرست کنترل دسترسی و/یا حذف اجباری را به روش Delete() ارسال کنید:

# 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 مراجعه کنید.

برگشتن به بالا