دليل Python

ملاحظة مهمة: تم كتابة هذا المستند قبل عام 2012. تم إيقاف خيارات المصادقة описанة في هذا المستند نهائيًا اعتبارًا من 20 نيسان (أبريل) 2012، ولم تعُد متاحة. وننصحك بنقل البيانات إلى OAuth 2.0 في أقرب وقت ممكن.

تسمح واجهة برمجة التطبيقات للبيانات في مواقع Google لتطبيقات العميل بالوصول إلى المحتوى ونشره وتعديله داخل موقع مصمم في مواقع Google. يمكن لتطبيق العميل أيضًا طلب قائمة بالأنشطة الحديثة واسترجاع سجلّ النُسخ السابقة وتنزيل المرفقات.

بالإضافة إلى تقديم بعض المعلومات الأساسية حول إمكانات Sites Data API، يقدّم هذا الدليل أمثلة على التفاعل مع واجهة برمجة التطبيقات باستخدام مكتبة Python للعملاء. للحصول على مساعدة في إعداد مكتبة العميل، يُرجى الاطّلاع على البدء في استخدام مكتبة Python Client Library لخدمة Google Data. إذا كنت مهتمًا بمعرفة المزيد عن البروتوكول الأساسي الذي تستخدمه مكتبة برامج Python للتفاعل مع واجهة برمجة تطبيقات "مواقع Google" الكلاسيكية، يُرجى الاطّلاع على دليل البروتوكول.

الجمهور

هذا المستند مخصّص للمطوّرين الذين يريدون كتابة تطبيقات عميل تتفاعل مع "مواقع Google" باستخدام مكتبة برامج Google Data Python.

الخطوات الأولى

لاستخدام مكتبة برامج Python، يجب توفُّر الإصدار 2.2 أو إصدار أحدث من Python والوحدات المدرَجة في صفحة DependencyModules على موقع wiki. بعد تنزيل مكتبة العميل، اطّلِع على البدء باستخدام مكتبة 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]

في حال عدم تقديم العلامات المطلوبة، سيطلب منك التطبيق إدخال هذه القيم. يسمح العيّنة للمستخدم بتنفيذ عدد من العمليات التي توضّح كيفية استخدام واجهة برمجة التطبيقات الكلاسيكية Sites API. ولذلك، عليك المصادقة لتنفيذ عمليات معيّنة (مثل تعديل المحتوى). سيطلب منك البرنامج أيضًا المصادقة من خلال AuthSub أو OAuth أو ClientLogin.

لتضمين الأمثلة الواردة في هذا الدليل في الرمز الخاص بك، ستحتاج إلى عبارات import التالية:

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

ستحتاج أيضًا إلى إعداد عنصر SitesClient الذي يمثّل اتصال العميل بواجهة برمجة التطبيقات الكلاسيكية لخدمة "مواقع Google". أدخِل اسم تطبيقك واسم مساحة الويب للموقع الإلكتروني (من عنوان 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"

يمكن استخدام مكتبة برامج Python للعمل مع الخلاصات العامة أو الخاصة. توفّر واجهة برمجة التطبيقات Sites Data API إمكانية الوصول إلى الخلاصات الخاصة والعامة، استنادًا إلى أذونات الموقع الإلكتروني والعملية التي تحاول تنفيذها. على سبيل المثال، قد تتمكّن من قراءة خلاصة المحتوى في موقع إلكتروني متاح للجميع، ولكن لا يمكنك إجراء تعديلات عليه، وهو إجراء يتطلّب عملاء تمّت مصادقة هويتهم. ويمكن إجراء ذلك من خلال مصادقة اسم المستخدم/كلمة المرور في ClientLogin أو AuthSub أو OAuth.

يُرجى الاطّلاع على نظرة عامة على مصادقة Google Data APIs للحصول على مزيد من المعلومات عن AuthSub وOAuth وClientLogin.

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" التي يملكها المستخدم أو لديه أذونات للاطّلاع عليها. ويمكن استخدامه أيضًا لتعديل اسم موقع إلكتروني حالي. أخيرًا، بالنسبة إلى نطاقات 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، والتي يمكنك استخدامها لتحديد معرّف موارد منتظم (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".
• يمكنك نسخ موقع إلكتروني من نطاق آخر، بشرط أن تكون مُدرَجًا على أنّك مالك على الموقع المصدر.

تعديل البيانات الوصفية لموقع إلكتروني

لتعديل عنوان موقع إلكتروني أو ملخّصه، ستحتاج إلى 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".

يمكنك جلب الأنشطة الأخيرة (التغييرات) لموقع إلكتروني من خلال جلب خلاصة الأنشطة. تتيح طريقة 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".

توفر خلاصة النُسخ السابقة معلومات عن سجل النُسخ السابقة لأي إدخال محتوى. يمكن استخدام الطريقة 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. اطّلِع على المصادقة على خدمة "مواقع Google".

تعرِض خلاصة المحتوى أحدث محتوى للموقع الإلكتروني. ويمكن الوصول إليه من خلال استدعاء 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)

استرداد صفحة حسب المسار

إذا كنت تعرف المسار النسبي لصفحة ضمن موقع 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 لنص الصفحة، ويضبط عنوان العنوان على "عنوان صفحة ويب جديد":

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 جديدة بعنوان "مساحة تخزين الملفات"، ولكنّه ينشئ الصفحة تحت عنوان 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 فارغًا إذا لم يكن اسم الصفحة متوفّرًا. تعني عملية التطبيع اقتطاع المسافات الفارغة وتجميعها إلى "-" وإزالة الأحرف التي لا تتطابق مع a-z, A-Z, 0-9, -, _.

إنشاء صفحات فرعية

لإنشاء صفحات فرعية (تابعة) ضمن صفحة رئيسية، استخدِم وسيطة الكلمة الرئيسية parent في CreatePage(). يمكن أن يكون parent إما gdata.sites.gdata.ContentEntry أو سلسلة تمثل معرّفًا ذاتيًا كاملاً لعنصر المحتوى.

يبحث هذا المثال في خلاصة المحتوى عن announcementpage وينشئ announcement جديدًا ضمن أول announcementpage يتم العثور عليه:

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"، تتيح واجهة برمجة التطبيقات تحميل المرفقات إلى صفحة خزانة ملفات أو صفحة رئيسية. يجب تحميل المرفقات إلى صفحة رئيسية. لذلك، يجب ضبط رابط رئيسي على 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. تشبه هذه الميزة طريقة التحميل إضافة ملف باستخدام عنوان URL في واجهة مستخدم "مواقع Google".

ملاحظة: لا يمكن إنشاء مرفقات الويب إلا ضمن 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)

يمكنك أيضًا تمرير 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" على طريقة مساعدة للوصول إلى الملف وتنزيله من هذا الرابط: 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

نظرة عامة على أذونات المشاركة (قوائم التحكّم بالوصول)

يمثّل كل إدخال في جدول أذونات الوصول في خلاصة جدول أذونات الوصول دور وصول لكيان معيّن، سواء كان مستخدمًا أو مجموعة مستخدمين أو نطاقًا أو إذن الوصول التلقائي (وهو موقع إلكتروني متاح للجميع). لن يتم عرض الإدخالات إلا للكيانات التي لديها إذن وصول صريح، وسيتم عرض إدخال واحد لكل عنوان بريد إلكتروني في لوحة "المستخدمون الذين لديهم إذن وصول" في شاشة المشاركة في واجهة مستخدم Google Sites. وبالتالي، لن يتمّ عرض مشرفي النطاق، على الرغم من أنّهم لديهم إذن وصول ضمني إلى موقع إلكتروني.

الأدوار

يمثل عنصر الدور مستوى الوصول الذي يمكن أن يتمتع به الكيان. هناك أربع قيم محتملة للعنصر gAcl:role:

• قارئ: مُشاهد (يعادل إذن الوصول للقراءة فقط)
• كاتب: متعاون (يعادل إذن الوصول للقراءة/التعديل)
• owner: يكون عادةً مشرف الموقع الإلكتروني (يعادل إذن الوصول للقراءة/الكتابة).

المستويات

يمثّل عنصر النطاق الكيان الذي يمتلك مستوى الوصول هذا. هناك أربعة أنواع محتملة للعنصر gAcl:scope:

• ‫user: قيمة عنوان بريد إلكتروني، مثل "user@gmail.com"
• المجموعة: عنوان بريد إلكتروني في "مجموعات Google"، مثل "المجموعة@النطاق.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. على سبيل المثال، يُستخدَم المقتطف التالي لاسترداد الموقع الإلكتروني الأول في خلاصة المواقع الإلكترونية للمستخدم وإجراء طلب بحث في خلاصة قائمة التحكّم بالوصول:

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" باستخدام واجهة برمجة التطبيقات، أنشئ 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 المعنيّ، وتعديل الإذن كما هو مطلوب، ثم طلب طريقة 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)

يمكنك أيضًا ضبط طريقة 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 API.

الرجوع إلى الأعلى

المواضيع الخاصة

استرداد خلاصة أو إدخال مرة أخرى

إذا كنت تريد استرداد خلاصة أو إدخال تم استرداده من قبل، يمكنك تحسين الكفاءة من خلال توجيه الخادم إلى إرسال القائمة أو الإدخال فقط في حال تم تغييرهما منذ آخر مرة تم استردادهما فيها.

لإجراء هذا النوع من الاسترجاع الشَرطي، عليك تمرير قيمة 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 API.

الرجوع إلى الأعلى