راهنمای پایتون

مهم: این سند قبل از سال 2012 نوشته شده است. گزینه های احراز هویت شرح داده شده در این سند (OAuth 1.0، AuthSub، و ClientLogin) از 20 آوریل 2012 به طور رسمی منسوخ شده اند و دیگر در دسترس نیستند. ما شما را تشویق می کنیم که در اسرع وقت به OAuth 2.0 مهاجرت کنید.

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

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

مخاطب

این سند برای توسعه دهندگانی در نظر گرفته شده است که می خواهند برنامه های مشتری بنویسند که با Google Data Python Client Library در تعامل با Google Sites هستند.

شروع کردن

برای استفاده از کتابخانه کلاینت پایتون، به پایتون 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 را تنظیم کنید، که نشان دهنده اتصال مشتری به 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 متغیر ایجاد کرده اید.

احراز هویت با Sites API کلاسیک

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

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

AuthSub برای برنامه های کاربردی وب

AuthSub Authentication برای برنامه های کاربردی وب باید توسط برنامه های سرویس گیرنده استفاده شود که باید کاربران خود را در حساب های 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 که یک کاربر مالک آن است یا مجوز مشاهده آنها را دارد استفاده کرد. همچنین می توان از آن برای تغییر نام یک سایت موجود استفاده کرد. در نهایت، برای دامنه‌های 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 در دسترس است.

سایت های جدید را می توان با فراخوانی متد 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 احراز هویت کند. به احراز هویت در سرویس سایت ها مراجعه کنید.

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

فید ویرایش اطلاعاتی در مورد تاریخچه بازبینی برای هر ورودی محتوا ارائه می دهد. متد GetRevisionFeed() می‌تواند برای واکشی ویرایش‌ها برای ورودی محتوای معین استفاده شود. این روش یک پارامتر 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 احراز هویت کند. به احراز هویت در سرویس سایت ها مراجعه کنید.

فید محتوا آخرین محتوای یک سایت را برمی گرداند. می توان با فراخوانی متد 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() برای ساخت 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)

بازیابی صفحه به مسیر

اگر مسیر نسبی یک صفحه را در سایت گوگل می دانید، می توانید از پارامتر 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 برای بدنه صفحه می شود و عنوان عنوان را روی «عنوان صفحه وب جدید» تنظیم می کند:

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 سفارشی

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

این مثال یک صفحه filecabinet جدید با عنوان «ذخیره‌سازی فایل» ایجاد می‌کند، اما صفحه را تحت نشانی اینترنتی http://sites.google.com/ domainName / siteName /files (به‌جای http://sites.google.com/ domainName / siteName /file-storage ایجاد می‌کند. 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 ، در صورت وجود. باید az, AZ, 0-9, -, _ برآورده کند.
2. title ، در صورت عدم وجود نام صفحه، نباید تهی باشد. عادی سازی عبارت است از برش + کوچک کردن فضای سفید به "-" و حذف نویسه هایی که با az, AZ, 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 حاوی یک کپی از پیوست ایجاد شده در سرور خواهد بود.

آپلود یک پیوست در یک پوشه

Filecabinets در 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')

توجه داشته باشید که این مثال به جای filepath یک شی 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 صفحه

ابرداده (عنوان، pageName، و غیره) و محتوای صفحه از هر نوع ورودی را می توان با استفاده از روش 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)

همچنین می‌توانید متد 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 محتوا است که می تواند برای دانلود محتوای فایل استفاده شود. سرویس گیرنده Sites حاوی یک روش کمکی برای دسترسی و دانلود فایل از این لینک است: DownloadAttachment() . یک 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 وجود دارد:

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

محدوده ها

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

• کاربر — یک مقدار آدرس ایمیل، به عنوان مثال "user@gmail.com".
• گروه — یک آدرس ایمیل گروه Google، به عنوان مثال "group@domain.com".
• دامنه — یک نام دامنه G Suite، به عنوان مثال «domain.com».
• پیش فرض — تنها یک محدوده ممکن از نوع "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 خود است. برای مثال، این قطعه اولین سایت را در فید Site کاربر واکشی می کند و فید 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 با استفاده از 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 در سرور فراخوانی کنید.

این مثال با به‌روزرسانی «user@example.com» به‌عنوان نویسنده (همکار)، acl_entry قبلی ما را از بخش اشتراک‌گذاری سایت تغییر می‌دهد:

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)

همچنین می‌توانید متد 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 را ببینید.

بازگشت به بالا