متوقّفة نهائيًا: تم إيقاف واجهة برمجة تطبيقات المواقع الإلكترونية نهائيًا وقد تتوقف عن العمل في أي وقت. يمكن لواجهة برمجة تطبيقات "مواقع Google" الوصول إلى "مواقع Google" الكلاسيكية فقط. لا يمكن لواجهة برمجة تطبيقات المواقع الوصول إلى الإصدار المُعاد تصميمه من المواقع الذي تم إطلاقه في 22 تشرين الثاني (نوفمبر) 2016.

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

دليل Python

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

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

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

الجمهور

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

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

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

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

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

راجِع استخدام بروتوكول OAuth مع مكتبات عميل Google Data API.

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

راجِع استخدام بروتوكول OAuth مع مكتبات عميل Google Data API.

ملاحظة: بعد حصول تطبيقك على رمز الدخول 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.

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

خلاصة الموقع

يمكن استخدام خلاصة الموقع لسرد مواقع 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.
يمكنك نسخ موقع إلكتروني من نطاق آخر في انتظار إدراجك كمالك على الموقع الإلكتروني المصدر.

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

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

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

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

يمكن تعديل البيانات الوصفية (العنوان واسم الصفحة وما إلى ذلك) ومحتوى الصفحة من أي نوع من الإدخالات بواسطة باستخدام طريقة 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

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

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

الأدوار

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

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

المستويات

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

user — قيمة عنوان بريد إلكتروني، مثل "user@gmail.com".
group — عنوان بريد إلكتروني لمجموعة 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). على سبيل المثال، يجلب هذا المقتطف أول موقع إلكتروني في خلاصة الموقع الإلكتروني للمستخدم ويُطلب من خلاصة قائمة التحكم بالوصول (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 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.

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

دليل Python

الجمهور

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

جارٍ تشغيل النموذج

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

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

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

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

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

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

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

جارٍ جلب رمز مميز للطلب

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

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

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

خلاصة الموقع

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

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

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

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

جارٍ جلب "خلاصة الأنشطة"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مرفقات الويب

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

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

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

حذف المحتوى

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

موجز ACL

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

الأدوار

المستويات

استرداد خلاصة قائمة التحكم بالوصول (ACL)

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

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

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

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

مواضيع خاصة

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