تم إطلاق إصدار جديد من "مواقع Google" في 22 تشرين الثاني (نوفمبر) 2016. لا يمكن لواجهة برمجة تطبيقات "مواقع Google" الوصول إلى "مواقع Google" التي تم إنشاؤها باستخدام هذا الإصدار أو تعديلها، ولكن لا يزال بإمكانها الوصول إلى مواقع Google الكلاسيكية.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

دليل Python

ملاحظة مهمة: تمت كتابة هذا المستند قبل عام 2012. تجدر الإشارة إلى أنّ خيارات المصادقة الموضحة في هذا المستند (OAuth 1.0 وAuthSub وClientLogin) تم إيقافها رسميًا اعتبارًا من 20 نيسان (أبريل) 2012، ولم تعد متاحة. ننصحك بالنقل إلى OAuth 2.0 في أقرب وقت ممكن.

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

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

الجمهور

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

البدء

لاستخدام مكتبة عملاء Python، ستحتاج إلى لغة Python 2.2 أو إصدار أحدث والوحدات مدرجة في صفحة DependencyModules على موقع wiki. بعد تنزيل مكتبة البرامج، راجِع بدء استخدام Google Data Python Library للحصول على مساعدة في تثبيت البرنامج واستخدامه.

تشغيل العيّنة

ويمكن الاطّلاع على عيّنة عمل كاملة في الدليل الفرعي 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]

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

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

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

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

المصادقة على واجهة برمجة التطبيقات للمواقع الكلاسيكية

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

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

AuthSub لتطبيقات الويب

يجب استخدام مصادقة AuthSub لتطبيقات الويب بواسطة تطبيقات العميل التي تحتاج إلى مصادقة المستخدمين على حسابات Google أو G Suite. لا يحتاج عامل التشغيل إلى الوصول إلى اسم المستخدم وكلمة المرور لمستخدم "مواقع Google"، بل يجب فقط رمز AuthSub مميز.

الاطّلاع على تعليمات دمج AuthSub في تطبيق الويب

طلب رمز مميّز يُستخدم لمرة واحدة

عندما يزور المستخدم تطبيقك لأول مرة، عليه المصادقة على التطبيق. عادةً ما يطبع مطوّرو البرامج بعض النصوص ورابطًا يوجّه المستخدم إلى صفحة الموافقة على AuthSub للمصادقة على المستخدم وطلب الوصول إلى مستنداته. توفّر مكتبة برامج Google Data Python دالة generate_auth_sub_url() لإنشاء عنوان URL هذا. يعمل الرمز أدناه على إعداد رابط يؤدي إلى صفحة AuthSubRequest.

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

إذا كنت ترغب في مصادقة المستخدمين على نطاق مستضاف في G Suite، أدخِل اسم النطاق إلى generate_auth_sub_url():

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)

تستخدم الطريقة generate_auth_sub_url() معلَمات متعدّدة (تتوافق مع مَعلمات طلب البحث التي يستخدمها معالج AuthSubRequest):

عنوان URL التالي: عنوان URL الذي سيعيد Google التوجيه إليه بعد أن يسجّل المستخدم الدخول إلى حسابه ويمنحه إمكانية الوصول، http://www.example.com/myapp.py في المثال أعلاه
النطاق - https://sites.google.com/feeds/
آمن، وهي قيمة منطقية للإشارة إلى ما إذا كان سيتم استخدام الرمز المميّز في الوضع الآمن والمسجّل أم لا. True في المثال أعلاه
session، وهي قيمة منطقية ثانية للإشارة إلى ما إذا كان سيتم لاحقًا استبدال الرمز المميز الذي يُستخدم لمرة واحدة برمز مميز للجلسة أم لا، True في المثال أعلاه.

ملاحظة: بعد أن يحصل تطبيقك بنجاح على رمز مميّز للجلسات الطويلة الأمد، يمكنك تخزين هذا الرمز المميّز في قاعدة البيانات لتذكّره لاستخدامه لاحقًا. ليس هناك حاجة إلى إعادة المستخدم إلى AuthSub عند كل تشغيل لتطبيقك. استخدِم client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) لضبط رمز مميَّز حالي على البرنامج.

بروتوكول OAuth للتطبيقات على الويب أو التطبيقات المثبّتة أو المتوافقة مع الأجهزة الجوّالة

يمكن استخدام OAuth كبديل لـ AuthSub، وهو مخصّص لتطبيقات الويب. يشبه بروتوكول OAuth استخدام الوضع الآمن والمسجّل في AuthSub حيث يجب توقيع جميع طلبات البيانات رقميًا، كما يجب تسجيل نطاقك.

الاطّلاع على التعليمات لدمج OAuth في تطبيقك المثبّت

جارٍ استرجاع رمز مميز للطلب

يُرجى الاطّلاع على استخدام OAuth مع Google Data API Client Libraries.

تفويض رمز مميز للطلب

يُرجى الاطّلاع على استخدام OAuth مع Google Data API Client Libraries.

الترقية إلى رمز دخول

يُرجى الاطّلاع على استخدام OAuth مع Google Data API Client Libraries.

ملاحظة: بعد حصول تطبيقك على رمز OAuth مميّز بنجاح، يمكنك تخزين هذا الرمز المميّز في قاعدة البيانات ليتم استخدامه لاحقًا. لا داعي لإعادة المستخدم عبر بروتوكول OAuth في كل مرة يتم فيها تشغيل تطبيقك. استخدِم client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) لضبط رمز مميَّز حالي على البرنامج.

ClientLogin للتطبيقات المثبتة/الجوّالة

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

اطّلع على تعليمات دمج ClientLogin في تطبيقك المثبَّت.

لاستخدام ClientLogin، استدعِ الطريقة ClientLogin() للكائن SitesClient الذي يتم اكتسابه من GDClient. حدد عنوان البريد الإلكتروني وكلمة المرور للمستخدم الذي يقدم عميلك الطلبات نيابةً عنه. مثال:

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

نصيحة: بعد أن ينجح تطبيقك في مصادقة المستخدم لأول مرة، يمكنك تخزين رمز المصادقة المميز في قاعدة البيانات لتذكُّره لاستخدامه لاحقًا. ليست هناك حاجة لمطالبة المستخدم بإدخال كلمة المرور عند كل تشغيل لتطبيقك. راجع استدعاء رمز مصادقة مميز لمزيد من المعلومات.

لمزيد من المعلومات عن استخدام ClientLogin في تطبيقات Python، يُرجى الاطّلاع على استخدام ClientLogin مع Google Data API Client Libraries.

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

خلاصة الموقع

يمكن استخدام خلاصة الموقع الإلكتروني لسرد مواقع 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).

في ما يلي مثال على إنشاء موقع إلكتروني جديد باستخدام المظهر "قائمة" وتقديم عنوان ووصف (اختياري):

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. يحتوي كل إدخال نشاط على معلومات حول التغيير الذي تم إجراؤه على الموقع.

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

جارٍ استرجاع سجلّ النُسخ السابقة

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

في ما يلي مثال على جلب خلاصة المحتوى بالكامل وطباعة بعض العناصر المثيرة للاهتمام:

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

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

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

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

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

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

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

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

  print

نصيحة: يمكن استخدام entry.Kind() لتحديد نوع الإدخال.

الكائن feed الناتج هو gdata.sites.data.ContentFeed يحتوي على قائمة gdata.sites.data.ContentEntry. يمثل كل إدخال صفحة/عنصر مختلف داخل موقع المستخدم ويحتوي على عناصر خاصة بنوع الإدخال. راجع نموذج التطبيق للحصول على فكرة أفضل عن بعض الخصائص المتاحة في كل نوع إدخال.

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

أمثلة على طلبات البحث في خلاصة المحتوى

يمكنك البحث في خلاصة المحتوى باستخدام بعض مَعلمات طلب البحث العادية في Google Data API ومَعلمات طلب البحث الخاصة بواجهة برمجة تطبيقات "مواقع Google" الكلاسيكية. للحصول على معلومات أكثر تفصيلاً وقائمة كاملة بالمعلَمات المتوافقة، يمكنك الاطّلاع على الدليل المرجعي.

ملاحظة: تستخدم الأمثلة الواردة في هذا القسم طريقة مساعد 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 للصفحة:

page_name، إن توفّرت. يجب أن تستوفي المعايير a-z, A-Z, 0-9, -, _.
title، يجب ألا يكون فارغًا في حال عدم توفّر اسم الصفحة. تتم التسوية من خلال قطع المسافة البيضاء وتصغيرها إلى "-" وإزالة الأحرف التي لا تتطابق مع a-z, A-Z, 0-9, -, _.

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

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

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

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

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

جارٍ تحميل الملفات

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

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)

لمزيد من المعلومات حول علامات ETag، يُرجى الاطّلاع على الدليل المرجعي لواجهات برمجة التطبيقات لبيانات Google.

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

تنزيل المرفقات

يحتوي كل إدخال 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

نظرة عامة على أذونات المشاركة (ACLs)

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

الأدوار

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

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

المستويات

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

المستخدم - قيمة عنوان بريد إلكتروني، مثل "user@gmail.com".
group - عنوان بريد إلكتروني لمجموعة من "مجموعات Google"، مثل "group@domain.com".
النطاق — اسم نطاق G Suite، مثل "domain.com".
default: ليس هناك سوى نطاق محتمل واحد من النوع "default"، والذي لا يتضمن أي قيمة (مثل <gAcl:scope type="default">). ويتحكّم هذا النطاق المعيّن في إمكانية الوصول التي يمكن لأي مستخدم تلقائيًا الوصول إليها على موقع إلكتروني متاح للجميع.

ملاحظة: لا يمكن ضبط القيمة gAcl:role على إذن وصول "المالك" للنطاقات، بل يمكن أن يكونوا قرّاء أو كتّاب فقط.

استرداد خلاصة ACL

يمكن استخدام خلاصة ACL للتحكم في أذونات مشاركة الموقع ويمكن استرجاعها باستخدام طريقة GetAclFeed().

يجلب المثال التالي خلاصة قائمة التحكم بالوصول (ACL) للموقع الإلكتروني المحدّد حاليًا على كائن SitesClient، ويطبع إدخالات الأذونات:

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

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

بعد إجراء طلب بحث ناجح، سيصبح feed عنصر gdata.sites.data.AclFeed يحتوي على قائمة gdata.sites.data.AclEntry.

إذا كنت تعمل على الإدخالات في SiteFeed، سيحتوي كل SiteEntry على رابط لخلاصة قائمة التحكم بالوصول (ACL). على سبيل المثال، يجلب هذا المقتطف الموقع الإلكتروني الأول في خلاصة الموقع للمستخدم ويبحث في خلاصة قائمة التحكم بالوصول (ACL) الخاصة به:

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

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

مشاركة موقع إلكتروني

ملاحظة: قد لا يكون من الممكن مشاركة بعض قوائم التحكم بالوصول (ACL) إلا إذا تم ضبط النطاق للسماح بمثل هذه الأذونات (على سبيل المثال، إذا تم تفعيل المشاركة خارج النطاق لنطاقات G Suite، وما إلى ذلك).

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

لمزيد من المعلومات حول علامات ETag، يُرجى الاطّلاع على الدليل المرجعي لواجهات برمجة التطبيقات لبيانات Google.

جارٍ إزالة أذونات المشاركة

لإزالة إذن مشاركة، عليك أولاً استرداد AclEntry، ثم طلب طريقة Delete() للعميل.

client.Delete(acl_entry)

يمكنك أيضًا ضبط طريقة Delete() على الرابط edit لإدخال نظام التحكم في الوصول إلى القائمة و/أو فرض الحذف:

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

لمزيد من المعلومات حول علامات ETag، يُرجى الاطّلاع على الدليل المرجعي لواجهات برمجة التطبيقات لبيانات Google.

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

مواضيع خاصة

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

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

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

لمزيد من المعلومات حول علامات ETag، يُرجى الاطّلاع على الدليل المرجعي لواجهات برمجة التطبيقات لبيانات Google.

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

دليل Python

الجمهور

البدء

تشغيل العيّنة

المصادقة على واجهة برمجة التطبيقات للمواقع الكلاسيكية

AuthSub لتطبيقات الويب

طلب رمز مميّز يُستخدم لمرة واحدة

الترقية إلى رمز مميز للجلسة

استرداد معلومات حول الرمز المميز للجلسة

إبطال الرمز المميز للجلسة

بروتوكول OAuth للتطبيقات على الويب أو التطبيقات المثبّتة أو المتوافقة مع الأجهزة الجوّالة

جارٍ استرجاع رمز مميز للطلب

تفويض رمز مميز للطلب

الترقية إلى رمز دخول

ClientLogin للتطبيقات المثبتة/الجوّالة

خلاصة الموقع

مواقع بطاقات البيانات

إنشاء مواقع جديدة

نسخ موقع إلكتروني

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

جلب خلاصة الأنشطة

جارٍ استرجاع سجلّ النُسخ السابقة

خلاصة المحتوى

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

أمثلة على طلبات البحث في خلاصة المحتوى

استرداد أنواع الإدخالات المحددة

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

استرداد جميع الإدخالات ضمن الصفحة الرئيسية

إنشاء المحتوى

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

إنشاء عناصر/صفحات ضمن مسارات عناوين URL المخصصة

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

جارٍ تحميل الملفات

جارٍ تحميل المرفقات…

تحميل مرفق إلى مجلد

مرفقات الويب

تحديث المحتوى

تعديل البيانات الوصفية للصفحة و/أو محتوى HTML

استبدال محتوى المرفق + البيانات الوصفية

حذف المحتوى

تنزيل المرفقات

خلاصة ACL

نظرة عامة على أذونات المشاركة (ACLs)

الأدوار

المستويات

استرداد خلاصة ACL

مشاركة موقع إلكتروني

المشاركة على مستوى المجموعة والنطاق

تعديل أذونات المشاركة

جارٍ إزالة أذونات المشاركة

مواضيع خاصة

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