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

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

دليل لغة Java

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

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

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

الجمهور

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

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

تستخدم مواقع Google حسابات Google أو حسابات G Suite للمصادقة. إذا كان لديك حساب، أنت جاهز الآن. أو يمكنك إنشاء حساب جديد.

تثبيت المكتبة

للحصول على مساعدة في إعداد مكتبة البرامج وتثبيتها، يمكنك الاطّلاع على بدء استخدام مكتبة برامج Java لبيانات Google. إذا كنت تستخدم Eclipse، ستوضّح هذه المقالة أيضًا كيفية إعداد مشروعك باستخدام المكوّن الإضافي Google Data APIs Eclipse. إليك ما تحتاجه للبدء:

تثبيت الإصدار 1.5 من Java أو إصدار أحدث
تنزيل مكتبة البرامج (أحدث إصدار من gdata-src.java.zip)
تنزيل قائمة العناصر التابعة
تنزيل نماذج التطبيقات (أحدث إصدار من gdata-samples.java.zip)

بعد تثبيت ملفات .jars، ستحتاج إلى تضمين ما يلي في مشروعك:

java/lib/gdata-sites-2.0.jar - الإصدار 2.0 هنا مخصّص للإصدار 1.4 من واجهة برمجة تطبيقات "مواقع Google" الكلاسيكية.
java/lib/gdata-core-1.0.jar
java/lib/gdata-client-1.0.jar
java/lib/gdata-spreadsheet-3.0.jar (في حالة العمل مع صفحات القائمة / عناصر القوائم)

تأكَّد أيضًا من تضمين حاويات التبعية (gdata-media-1.0.jar وmail.jar وgoogle-collect....jar).

تشغيل نموذج التطبيق

يتوفّر نموذج تطبيق كامل يعمل في الدليل الفرعي /java/sample/sites من تنزيل gdata-samples.java.zip. يتوفّر المصدر أيضًا على /trunk/java/sample/sites/. في مستودع SVN الذي يمكن الوصول إليه من علامة تبويب المصدر. تتيح SitesDemo.java للمستخدم إجراء عدد من العمليات التي توضح كيفية استخدام الإصدار الكلاسيكي من "مواقع Google".

تجدر الإشارة إلى أنّك ستحتاج إلى تضمين java/sample/util/lib/sample-util.jar لتشغيل النموذج.

بدء مشروعك الخاص

نصيحة: راجِع المقالة استخدام Eclipse مع Google Data APIs لإجراء إعداد سريع باستخدام المكوّن الإضافي Eclipse.

حسب احتياجات تطبيقك، ستحتاج إلى عمليات استيراد متعددة. وننصحك بالبدء بعمليات الاستيراد التالية:

import com.google.gdata.client.*;
import com.google.gdata.client.sites.*;
import com.google.gdata.data.*;
import com.google.gdata.data.acl.*;
import com.google.gdata.data.media.*;
import com.google.gdata.data.sites.*;
import com.google.gdata.data.spreadsheet.*;  // If working with listpages / listitems
import com.google.gdata.util.*;

بعد ذلك، عليك أيضًا إعداد عنصر SitesService يمثّل اتصال عميل بواجهة برمجة تطبيقات "مواقع Google" الكلاسيكية:

SitesService client = new SitesService("yourCo-yourAppName-v1");

يجب أن تتبع الوسيطة applicationName التنسيق: company-applicationname-version. تُستخدم هذه المعلمة لأغراض التسجيل.

ملاحظة: يفترض الجزء المتبقي من هذا الدليل أنّك أنشأت SitesService في المتغيّر client.

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

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

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

ملاحظة: تتوافق واجهة برمجة التطبيقات مع طبقة المقابس الآمنة (HTTPS). في حال استخدام AuthSub/OAuth، احرص على تحديد نطاق https://sites.google.com/feeds/ لطلب خلاصات عبر طبقة المقابس الآمنة. لاحظ أيضًا أنه بالنسبة G Suite، خيار "يتطلب طبقة المقابس الآمنة (SSL)" تحترم واجهة برمجة التطبيقات الإعدادات الموجودة في لوحة التحكم الإدارية. يمكنك فرض كل تطلب واجهة برمجة التطبيقات استخدام بروتوكول HTTPS من خلال طلب الرقم client.useSsl();.

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

يجب استخدام مصادقة AuthSub لتطبيقات الويب من خلال تطبيقات العميل التي تحتاج إلى مصادقة المستخدمين على حسابات Google. لا يحتاج المُشغِّل إلى الوصول إلى اسم المستخدم وكلمة المرور لمستخدم "مواقع Google" - فقط يجب إدخال رمز AuthSub المميّز.

عرض التعليمات حول دمج AuthSub في تطبيق الويب

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

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

import com.google.gdata.client.*;

String nextUrl = "http://www.example.com/welcome.jsp";
String scope = "https://sites.google.com/feeds/";
boolean secure = true;
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);

إذا كنت ترغب في مصادقة المستخدمين في نطاقك المستضاف على G Suite، يُرجى اتّباع الخطوات التالية:

import com.google.gdata.client.*;

String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/welcome.jsp";
String scope = "https://sites.google.com/feeds/";  // SSL is also supported
boolean secure = true;
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);

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

عنوان URL التالي، وهو عنوان URL الذي سيعيد محرّك بحث Google التوجيه إليه بعد أن يسجّل المستخدم الدخول إلى حسابه ويمنحه إذن الوصول http://www.example.com/welcome.jsp في المثال أعلاه
النطاق — https://sites.google.com/feeds/ في المثال أعلاه
قيمة منطقية للإشارة إلى ما إذا كان الرمز المميّز سيتم استخدامه في الوضع المسجَّل أم لا false في المثال أعلاه
قيمة منطقية ثانية للإشارة إلى ما إذا كان سيتم استبدال الرمز المميّز للجلسة أم لا true في المثال أعلاه

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

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

عرض تعليمات دمج بروتوكول OAuth في تطبيقك المثبَّت

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

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

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

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

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

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

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

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

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

لاستخدام ClientLogin، استدعِ الرمز setUserCredentials() طريقة كائن SitesService المكتسَبة من GoogleService تحديد عنوان البريد الإلكتروني وكلمة المرور للمستخدم نيابةً عن الشخص الذي يقدم عميلك الطلبات. على سبيل المثال:

SitesService client = new SitesService("yourCo-yourAppName-v1");
client.setUserCredentials("example@gmail.com", "pa$$word");

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

لمزيد من المعلومات عن استخدام ClientLogin في تطبيقات Java، يمكنك الاطّلاع على استخدام ClientLogin مع مكتبات عميل Google Data API.

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

خلاصة الموقع

يمكن استخدام خلاصة الموقع لسرد مواقع Google التي يملكها المستخدم أو لديه أذونات عرض لها. ويمكن استخدامه أيضًا لتعديل اسم موقع إلكتروني حالي. بالنسبة إلى نطاقات G Suite، يمكن استخدامها أيضًا لإنشاء و/أو نسخ بأكمله.

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

لطلب بحث عن خلاصة الموقع الإلكتروني، أرسِل HTTP GET إلى عنوان URL لخلاصة الموقع الإلكتروني:

https://sites.google.com/feeds/site/site/

في برنامج Java، يمكنك استخدام الصفَّين SiteFeed وSiteEntry للعمل. مع خلاصة الموقع:

public String getSiteFeedUrl() {
  String domain = "site";  // OR if the Site is hosted on G Suite, your domain (e.g. example.com)
  return "https://sites.google.com/feeds/site/" + domain + "/";
}

public void getSiteFeed() throws IOException, ServiceException {
  SiteFeed siteFeed = client.getFeed(new URL(getSiteFeedUrl()), SiteFeed.class);
  for (SiteEntry entry : siteFeed.getEntries()){
    System.out.println("title: " + entry.getTitle().getPlainText());
    System.out.println("site name: " + entry.getSiteName().getValue());
    System.out.println("theme: " + entry.getTheme().getValue());
    System.out.println("");
  }
}

يطبع المقتطف أعلاه عنوان الموقع الإلكتروني واسمه ومظهره. تتوفر مصادر أخرى للحصول على الوصول إلى مواقع إضافية في الخلاصة

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

ملاحظة: لا تتوفّر هذه الميزة إلا لنطاقات G Suite.

يمكن إدارة حسابات المواقع الإلكترونية الجديدة من خلال إنشاء SiteEntry جديدة وطلب insert() على خلاصة الموقع الإلكتروني.

ينشئ هذا المثال موقعًا إلكترونيًا جديدًا باستخدام الموضوع "slate" (إعداد اختياري) وتقدم اسم الموقع (مطلوب) ووصفه (اختياري):

public String getSiteFeedUrl() {
  String domain = "example.com";
  return "https://sites.google.com/feeds/site/" + domain + "/";
}

public SiteEntry createSite(String title, String summary, String theme, String tag)
    throws MalformedURLException, IOException, ServiceException {
  SiteEntry entry = new SiteEntry();
  entry.setTitle(new PlainTextConstruct(title));
  entry.setSummary(new PlainTextConstruct(summary));

  Theme tt = new Theme();
  tt.setValue(theme);
  entry.setTheme(tt);

  entry.getCategories().add(new Category(TagCategory.Scheme.TAG, tag, null));

  return client.insert(new URL(getSiteFeedUrl()), entry);
}

SiteEntry newSiteEntry = createSite("My Site Title", "summary for site", "slate", "tag");

سيؤدي الطلب أعلاه إلى إنشاء موقع إلكتروني جديد ضمن نطاق G Suite example.com. وبالتالي، سيكون عنوان URL للموقع الإلكتروني هو https://sites.google.com/a/example.com/my-site-title.

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

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

ملاحظة: لا تتوفّر هذه الميزة إلا لنطاقات G Suite.

يشبه نسخ موقع إلكتروني إنشاء موقع إلكتروني جديد. الفرق هو أنك بحاجة إلى تعيين في SiteEntry الجديد الذي يتضمن الرابط الذاتي للموقع الإلكتروني لإنشاء نسخة طبق الأصل منه. في ما يلي مثال على تكرار الموقع الذي تم إنشاؤه في القسم إنشاء مواقع جديدة:

public SiteEntry copySite(String title, String summary, String sourceHref)
    throws MalformedURLException, IOException, ServiceException {
  SiteEntry entry = new SiteEntry();
  entry.setTitle(new PlainTextConstruct(title));
  entry.setSummary(new PlainTextConstruct(summary));
  entry.addLink(SitesLink.Rel.SOURCE, Link.Type.ATOM, sourceHref);

  return client.insert(new URL(getSiteFeedUrl()), entry);
}

String sourceHref = newSiteEntry.getLink(SitesLink.Rel.SOURCE, Link.Type.ATOM).getHref();
SiteEntry myTwin = copySite("Duplicate Site", "A copy", sourceHref);

نقاط مهمة:

لا يمكن نسخ سوى المواقع الإلكترونية ونماذج المواقع الإلكترونية التي يملكها المستخدم الذي تمت المصادقة عليه.
يمكن أيضًا نسخ نموذج موقع. ويكون الموقع الإلكتروني نموذجًا إذا كانت عبارة "نشر هذا الموقع كنموذج" الإعداد في صفحة إعدادات مواقع Google.
يمكنك نسخ موقع إلكتروني من نطاق آخر في انتظار إدراجك كمالك على الموقع الإلكتروني المصدر.

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

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

myTwin.setTitle(new PlainTextConstruct("better-title"));

Theme theme = myTwin.getTheme();
theme.setValue('iceberg');
myTwin.setTheme(theme);

myTwin.getCategories().add(new Category(TagCategory.Scheme.TAG, "newTag", null));

SiteEntry updatedSiteEntry = myTwin.update();

System.out.println(updatedSiteEntry.getTitle().getPlainText();

تعيينات عناوين الويب

تمكّن عمليات ربط عناوين الويب مستخدمي "مواقع Google" من ربط نطاقاتهم الخاصة بأحد "مواقع Google". على سبيل المثال: http://www.mydomainsite.com يمكن استخدامها بدلاً من http://sites.google.com/a/domain.com/mysite. يمكنك تعديل تعيينات عناوين الويب للموقع. يمكنك الاطّلاع على مقالة مركز المساعدة للحصول على مزيد من المعلومات.

جارٍ استرجاع عمليات ربط عناوين الويب لأحد المواقع الإلكترونية

لعرض عمليات ربط عناوين الويب لأحد المواقع الإلكترونية، عليك جلب إدخال/خلاصة الموقع الإلكتروني باستخدام المَعلمة with-mappings=true:

SiteQuery query = new SiteQuery(new URL("https://sites.google.com/feeds/site/siteName"));
query.setWithMappings(true);

SiteFeed feed = service.getFeed(query, SiteFeed.class);
for (SiteEntry entry : feed.getEntries()) {
  System.out.println("Mappings for '" + entry.getSiteName().getValue() + "':");
  for (Link link : entry.getWebAddressMappingLinks()) {
    System.out.println("  " + link.getHref());
  }
}

ستظهر عمليات الربط الحالية على أنّها link مع rel='webAddressMapping'. على سبيل المثال، في المثال أعلاه هناك ثلاث نقاط webAddressMapping تشير إلى الموقع الإلكتروني. http://sites.google.com/site/myOtherTestSite

تعديل تعيينات عناوين الويب

ملاحظة: يجب أن تحدد جميع عمليات GET/POST/PUT المعلمة with-mappings=true عند العمل. من خلال تعيينات عناوين الويب. في حال عدم توفّر المَعلمة، لن يتم عرض webAddressMapping في إدخالات الموقع الإلكتروني (GET) أو لن يتم أخذها في الاعتبار. عند تحديث/إزالة تعيينات (PUT) من إدخال.

لإضافة عملية ربط أو تحديثها أو حذفها، ما عليك سوى تحديد هذا الرابط أو تغييره أو إزالته عند إنشاء مواقع إلكترونية جديدة. تعديل البيانات الوصفية للموقع الإلكتروني يجب تضمين المَعلمة with-mappings=true في معرّف الموارد المنتظم (URI) لخلاصة الموقع الإلكتروني. ملاحظة: لتعديل عمليات ربط العناوين، يجب أن تكون مشرف الموقع الإلكتروني أو مشرف نطاق في حال استخدام موقع إلكتروني مستضاف على G Suite.

على سبيل المثال، يعدّل الطلب أدناه عملية ربط http://www.mysitemapping.com إلى http://www.my-new-sitemapping.com. وإزالة http://www.mysitemapping2.com من خلال ترك الرابط خارج الإدخال:

SiteEntry entry = client.getEntry(new URL("https://sites.google.com/feeds/site/site/siteName?with-mappings=true"), SiteEntry.class);

// Modify mappings (remove all mappings, add some of them again, add modified mappings)
entry.removeLinks(SitesLink.Rel.WEBADDRESSMAPPING, Link.Type.HTML);
entry.addLink(SitesLink.Rel.WEBADDRESSMAPPING, Link.Type.HTML, "http://www.my-new-sitemapping.com");

// Update the entry with the mappings.
entry.update();

ملاحظة: يمكن أيضًا تحديد تعيينات عنوان الويب في وقت إنشاء/نسخ موقع إلكتروني.

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

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

يمكنك استرجاع الأنشطة (التغييرات) الحديثة لأحد المواقع الإلكترونية من خلال استرجاع خلاصة الأنشطة. كل إدخال في تحتوي خلاصة الأنشطة على معلومات حول تغيير تم إجراؤه في الموقع.

للاستعلام عن خلاصة الأنشطة، أرسِل HTTP GET إلى عنوان URL لخلاصة الأنشطة:

https://sites.google.com/feeds/activity/site/siteName

في برنامج Java، استخدِم الفئة ActivityFeed لعرض كائنات ActivityEntry:

public String buildActivityFeedUrl() {
  String domain = "site";  // OR if the Site is hosted on G Suite, your domain (e.g. example.com)
  String siteName = "mySite";
  return "https://sites.google.com/feeds/activity/" + domain + "/" + siteName + "/";
}

public void getActivityFeed() throws IOException, ServiceException {
  ActivityFeed activityFeed = client.getFeed(new URL(buildActivityFeedUrl()), ActivityFeed.class);
  for (BaseActivityEntry<?> entry : activityFeed.getEntries()){
    System.out.println(entry.getSummary().getPlainText());
    System.out.println(" revisions link: " + entry.getRevisionLink().getHref());
  }
}

ملاحظة: يتطلب الوصول إلى هذه الخلاصة أن تكون أحد المتعاونين أو المالك للموقع الإلكتروني. يجب أن يجري العميل المصادقة باستخدام رمز مميز لـ AuthSub أو OAuth أو ClientLogin. يُرجى الاطّلاع على المصادقة على خدمة "مواقع Google".

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

خلاصة المراجعات

لجلب سجلّ النُسخ السابقة لأي إدخال محتوى، أرسِل HTTP GET إلى رابط مراجعة الإدخال:

https://sites.google.com/feeds/revision/site/siteName/CONTENT_ENTRY_ID

يطلب هذا المثال خلاصة المحتوى، ثم يسترجع خلاصة النُسخة السابقة لإدخال المحتوى الأول:

ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl()), ContentFeed.class);
URL revisionFeedUrl = new URL(contentFeed.getEntries().get(0).getRevisionLink().getHref()); // use first entry

public void getRevisionFeed(String revisionFeedUrl) throws IOException, ServiceException {
  RevisionFeed revisionFeed = client.getFeed(revisionFeedUrl, RevisionFeed.class);
  for (BaseContentEntry<?> entry : revisionFeed.getEntries()){
    System.out.println(entry.getTitle().getPlainText());
    System.out.println(" updated: " + entry.getUpdated().toUiString() + " by " +
        entry.getAuthors().get(0).getEmail());
    System.out.println(" revision #: " + entry.getRevision().getValue());
  }
}

ملاحظة: يتطلب الدخول إلى هذه الخلاصة أن تكون أحد المتعاونين أو المالك للموقع الإلكتروني. يجب أن يجري العميل المصادقة باستخدام رمز مميز لـ AuthSub أو OAuth أو ClientLogin. يُرجى الاطّلاع على المصادقة على خدمة "مواقع Google".

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

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

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

تعرض خلاصة المحتوى أحدث محتوى للموقع الإلكتروني. ويمكن الوصول إليه من خلال إرسال HTTP GET إلى عنوان URL لخلاصة المحتوى:

https://sites.google.com/feeds/content/site/siteName

معلمة الخلاصة	الوصف
`site`	"`site`" أو نطاق نطاقك المستضاف على G Suite (مثل `example.com`).
`siteName`	اسم مساحة الويب لموقعك الإلكتروني في عنوان URL الخاص بالموقع الإلكتروني (مثل `mySite`).

مثال على استرجاع خلاصة المحتوى:

public String buildContentFeedUrl() {
  String domain = "site";  // OR if the Site is hosted on G Suite, your domain (e.g. example.com)
  String siteName = "mySite";
  return "https://sites.google.com/feeds/content/" + domain + "/" + siteName + "/";
}

ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl()), ContentFeed.class);

عنصر contentFeed الناتج هو كائن ContentFeed يحتوي على الاستجابة من الخادم. كل إدخال تمثل contentFeed صفحة أو عنصرًا مختلفًا داخل موقع المستخدم. ستتضمّن ContentFeed أنواعًا مختلفة. من العناصر، كلها مكتسَبة من BaseContentEntry: ListItemEntry وListPageEntry وAttachmentEntry وWebAttachmentEntry FileCabinetPageEntry، AnnouncementsPageEntry، AnnouncementEntry، WebPageEntry، CommentEntry.

في ما يلي مثال على إدراج الأنواع المختلفة من الإدخالات في ContentFeed. يحتوي كل نوع من الإدخالات على خصائص مختلفة، ولكن ليست كلها مطبوعة هنا.

public String getContentBlob(BaseContentEntry<?> entry) {
 return ((XhtmlTextConstruct) entry.getTextContent().getContent()).getXhtml().getBlob();
}

// Extracts an entry's numeric ID.
private String getEntryId(String selfLink) {
  return selfLink.substring(selfLink.lastIndexOf("/") + 1);
}

public void printContentEntries(ContentFeed contentFeed) {
  System.out.println("Listing all WebPageEntry:");
  for (WebPageEntry entry : contentFeed.getEntries(WebPageEntry.class)) {
    System.out.println(" title: " + entry.getTitle().getPlainText());
    System.out.println(" id: " + getEntryId(entry));
    if (entry.getParentLink() != null) {
      System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
    }
    System.out.println(" author: " + entry.getAuthors().get(0).getEmail());
    System.out.println(" content: " + getContentBlob(entry));
  }

  System.out.println("Listing all ListPageEntry:");
  for (ListPageEntry entry : contentFeed.getEntries(ListPageEntry.class)) {
    System.out.println(" title: " + entry.getTitle().getPlainText());
    System.out.println(" id: " + getEntryId(entry));
    for (Column col : entry.getData().getColumns()) {
      System.out.print(" [" + col.getIndex() + "] " + col.getName() + "\t");
    }
  }

  for (ListItemEntry entry : contentFeed.getEntries(ListItemEntry.class)) {
    for (Field field : entry.getFields()) {
      System.out.print(" [" + field.getIndex() + "] " + field.getValue() + "\t");
    }
    System.out.println("\n");
  }

  System.out.println("Listing all FileCabinetPageEntry:");
  for (FileCabinetPageEntry entry : contentFeed.getEntries(FileCabinetPageEntry.class)) {
    System.out.println(" title: " + entry.getTitle().getPlainText());
    System.out.println(" id: " + getEntryId(entry));
    System.out.println(" content: " + getContentBlob(entry));
  }

  System.out.println("Listing all CommentEntry:");
  for (CommentEntry entry : contentFeed.getEntries(CommentEntry.class)) {
    System.out.println(" in-reply-to: " + entry.getInReplyTo().toString());
    System.out.println(" content: " + getContentBlob(entry));
  }

  System.out.println("Listing all AnnouncementsPageEntry:");
  for (AnnouncementsPageEntry entry : contentFeed.getEntries(AnnouncementsPageEntry.class)) {
    System.out.println(" title: " + entry.getTitle().getPlainText());
    System.out.println(" id: " + getEntryId(entry));
    System.out.println(" content: " + getContentBlob(entry));
  }

  System.out.println("Listing all AnnouncementEntry:");
  for (AnnouncementEntry entry : contentFeed.getEntries(AnnouncementEntry.class)) {
    System.out.println(" title: " + entry.getTitle().getPlainText());
    System.out.println(" id: " + getEntryId(entry));
    if (entry.getParentLink() != null) {
      System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
    }
    System.out.println(" draft?: " + entry.isDraft());
    System.out.println(" content: " + getContentBlob(entry));
  }

  System.out.println("Listing all AttachmentEntry:");
  for (AttachmentEntry entry : contentFeed.getEntries(AttachmentEntry.class)) {
    System.out.println(" title: " + entry.getTitle().getPlainText());
    System.out.println(" id: " + getEntryId(entry));
    if (entry.getParentLink() != null) {
      System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
    }
    if (entry.getSummary() != null) {
      System.out.println(" description: " + entry.getSummary().getPlainText());
    }
    System.out.println(" revision: " + entry.getRevision().getValue());
    MediaContent content = (MediaContent) entry.getContent();
    System.out.println(" src: " + content.getUri());
    System.out.println(" content type: " + content.getMimeType().getMediaType());
  }

  System.out.println("Listing all WebAttachmentEntry:");
  for (WebAttachmentEntry entry : contentFeed.getEntries(WebAttachmentEntry.class)) {
    System.out.println(" title: " + entry.getTitle().getPlainText());
    System.out.println(" id: " + getEntryId(entry));
    if (entry.getParentLink() != null) {
      System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
    }
    if (entry.getSummary() != null) {
      System.out.println(" description: " + entry.getSummary().getPlainText());
    }
    System.out.println(" src: " + ((MediaContent) entry.getContent()).getUri());
  }
}

ملاحظة: قد تتطلّب هذه الخلاصة مصادقة أو لا تتطلّب المصادقة. استنادًا إلى أذونات المشاركة للموقع الإلكتروني. إذا لم يكن الموقع متاحًا للجميع، يجب على العميل المصادقة باستخدام رمز AuthSub أو OAuth أو ClientLogin. عرض المصادقة على خدمة "مواقع Google":

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

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

ملاحظة: تستخدم الأمثلة الواردة في هذا القسم طريقة buildContentFeedUrl() في استرداد خلاصة المحتوى.

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

لاسترجاع نوع معيّن من الإدخالات، استخدِم المَعلمة kind. يعرض هذا المثال attachment إدخال فقط:

ContentQuery query = new ContentQuery(new URL(buildContentFeedUrl()));
query.setKind("webpage");
ContentFeed contentFeed = client.getFeed(query, ContentFeed.class);
for (AttachmentEntry entry : contentFeed.getEntries(AttachmentEntry.class)) {
  System.out.println(entry.getTitle().getPlainText());
}

لعرض أكثر من نوع إدخال واحد، يجب الفصل بين كل kind باستخدام ','. يعرض هذا المثال filecabinet listpage إدخال:

URL url = new URL(buildContentFeedUrl() + "?kind=filecabinet,listpage");
ContentFeed contentFeed = client.getFeed(url, ContentFeed.class);
for (FileCabinetPageEntry entry : contentFeed.getEntries(FileCabinetPageEntry.class)) {
  System.out.println(" title: " + entry.getTitle().getPlainText());
}
for (ListPageEntry entry : contentFeed.getEntries(ListPageEntry.class)) {
  System.out.println(" title: " + entry.getTitle().getPlainText());
}

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

إذا كنت تعرف المسار النسبي لإحدى الصفحات داخل موقع Google، يمكنك استخدام مَعلمة path لاسترجاع تلك الصفحة المحدّدة. سيعرض هذا المثال الصفحة الموجودة على http://sites.google.com/site/siteName/path/to/the/page:

ContentQuery query = new ContentQuery(new URL(buildContentFeedUrl()));
query.setPath("/path/to/the/page");
ContentFeed contentFeed = client.getFeed(query, ContentFeed.class);
for (BaseContentEntry<?> entry : contentFeed.getEntries()) {
  System.out.println(" title: " + entry.getTitle().getPlainText());
}

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

إذا كنت تعرف معرّف إدخال المحتوى لإحدى الصفحات (على سبيل المثال، "1234567890" في المثال أدناه)، يمكنك استخدام مَعلمة parent. لجلب جميع إدخالاته الفرعية (إن وجدت):

ContentQuery query = new ContentQuery(new URL(buildContentFeedUrl()));
query.setParent("1234567890");
ContentFeed contentFeed = client.getFeed(query, ContentFeed.class);

للحصول على معلَمات إضافية، يمكنك الاطّلاع على الدليل المرجعي.

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

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

ملاحظة: قبل إنشاء محتوى لموقع إلكتروني، تأكَّد من ضبط موقعك الإلكتروني في البرنامج.
client.site = "siteName";

يمكن إنشاء محتوى جديد (صفحات الويب وصفحات القوائم وصفحات خزانات الملفات وصفحات الإعلانات وما إلى ذلك) عن طريق إرسال HTTP POST. إلى خلاصة المحتوى:

https://sites.google.com/feeds/content/site/siteName

للحصول على قائمة بأنواع عُقد الدعم، يُرجى الاطّلاع على المَعلمة kind في الدليل المرجعي.

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

يؤدي هذا المثال إلى إنشاء علامة webpage جديدة ضمن المستوى الأعلى للموقع الإلكتروني، وتتضمّن بعض رموز XHTML للنص الأساسي في الصفحة. وتعيين عنوان العنوان على "عنوان صفحة ويب جديدة":

private void setContentBlob(BaseContentEntry<?> entry, String pageContent) {
  XmlBlob xml = new XmlBlob();
  xml.setBlob(pageContent);
  entry.setContent(new XhtmlTextConstruct(xml));
}

public WebPageEntry createWebPage(String title, String content)
    throws MalformedURLException, IOException, ServiceException {
  WebPageEntry entry = new WebPageEntry();
  entry.setTitle(new PlainTextConstruct(title));

  setContentBlob(entry, content); // Entry's HTML content

  return client.insert(new URL(buildContentFeedUrl()), entry);
}

WebPageEntry createdEntry = createWebPage("New Webpage Title", "<b>HTML content</b>");
System.out.println("Created! View at " + createdEntry.getHtmlLink().getHref());

إذا تم الطلب بنجاح، سيحتوي createdEntry على نسخة من الإدخال الذي تم إنشاؤه على الخادم.

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

سيتم تلقائيًا إنشاء المثال السابق ضمن عنوان URL http://sites.google.com/site/siteName/new-webpage-title و يكون لها عنوان صفحة "عنوان صفحة ويب جديدة". وهذا يعني أنّه تمت تسوية قيمة <atom:title> إلى new-webpage-title لعنوان URL. لتخصيص مسار عنوان URL لصفحة ما، يمكنك ضبط عنصر <sites:pageName>.

ينشئ هذا المثال صفحة filecabinet جديدة بعنوان "تخزين الملفات"، ولكن يتم إنشاء الصفحة. ضمن عنوان URL http://sites.google.com/site/siteName/files (بدلاً من http://sites.google.com/site/siteName/file-storage) من خلال تحديد العنصر <sites:pageName>.

public FileCabinetPageEntry createFileCabinetPage(String title, String content, String customPageName)
    throws MalformedURLException, IOException, ServiceException {
  FileCabinetPageEntry entry = new FileCabinetPageEntry();
  entry.setTitle(new PlainTextConstruct(title));

  setContentBlob(entry, content); // Entry's HTML content

  entry.setPageName(new PageName(customPageName)); // Upload to a custom page path

  return client.insert(new URL(buildContentFeedUrl()), entry);
}

FileCabinetPageEntry createdEntry = createFileCabinetPage("File Storage", "<b>HTML content</b>", "files");
System.out.println("Created! View at " + createdEntry.getHtmlLink().getHref());

يستخدم الخادم قواعد الأولوية التالية لتسمية مسار عنوان URL للصفحة:

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

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

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

public AnnouncementEntry postAnnouncement(String title, String content, AnnouncementsPageEntry parentPage)
    throws MalformedURLException, IOException, ServiceException {
  AnnouncementEntry entry = new AnnouncementEntry();
  entry.setTitle(new PlainTextConstruct(title));

  setContentBlob(entry, content); // Entry's HTML content

  // Set the entry's parent link to create the announcement under that page.
  entry.addLink(SitesLink.Rel.PARENT, Link.Type.ATOM, parentPage.getSelfLink().getHref());

  return client.insert(new URL(buildContentFeedUrl()), entry);
}

ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl() + "?kind=announcementspage"), ContentFeed.class);

AnnouncementEntry createdEntry = postAnnouncement("Party!!", "My place, this weekend", contentFeed.getEntries().get(0));
System.out.println("New post by " + createdEntry.getAuthors().get(0).getName());

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

نماذج الصفحات

إنشاء نماذج الصفحات

تتشابه عملية إنشاء نموذج الصفحة مع إنشاء عناصر/صفحات جديدة. إنشاء صفحات فرعية: يكمن الاختلاف في إضافة category مع ضبط العبارة والتصنيف على "http://schemas.google.com/g/2005#template". و"template" على التوالي.

ينشئ هذا المثال نموذج webpage جديدًا.

// The template webpage entry.
WebPageEntry entry = new WebPageEntry();

// Set title and content.
entry.setTitle(new PlainTextConstruct("Page template title"));
XmlBlob xml = new XmlBlob();
xml.setBlob("Content for page template");
entry.setContent(new XhtmlTextConstruct(xml));

// Set the template category
Category TEMPLATE_CATEGORY = new Category(TemplateCategory.Scheme.LABELS,
    TemplateCategory.Term.TEMPLATE, TemplateCategory.Label.TEMPLATE);
entry.getCategories().add(TEMPLATE_CATEGORY);

// Insert the template webpage entry.
WebPageEntry createdEntry = client.insert(new URL("https://sites.google.com/feeds/content/site/siteName"), entry);

إنشاء صفحات من نموذج

كما هو الحال في إنشاء نماذج الصفحات، يمكنك إنشاء مثيل لصفحة جديدة من نموذج من خلال تضمين <link> باستخدام rel='http://schemas.google.com/sites/2008#template' مُشارًا إلى الرابط الذاتي لقالب الصفحة.

ينشئ هذا المثال نموذج filecabinet جديدًا ثم ينشئ صفحة filecabinet جديدة من ذلك النموذج.

URL feedUrl = new URL("https://sites.google.com/feeds/content/site/siteName");

// 1. Create file cabinet page template
FileCabinetPageEntry inputTemplateEntry = new FileCabinetPageEntry();
inputTemplateEntry.setTitle(new PlainTextConstruct("File cabinet page template title"));
XmlBlob xml = new XmlBlob();
xml.setBlob("Content for page template");
inputTemplateEntry.setContent(new XhtmlTextConstruct(xml));

// Set the template category
Category TEMPLATE_CATEGORY = new Category(TemplateCategory.Scheme.LABELS,
    TemplateCategory.Term.TEMPLATE, TemplateCategory.Label.TEMPLATE);
inputTemplateEntry.getCategories().add(TEMPLATE_CATEGORY);

// 2. Create file cabinet page template instance
FileCabinetPageEntry templateEntry = client.insert(feedUrl, inputTemplateEntry);

// Specify link to the page template
FileCabinetPageEntry templateInstanceEntry = new FileCabinetPageEntry();
templateInstanceEntry.setTitle(new PlainTextConstruct("File cabinet template instance"));
templateInstanceEntry.addLink(new Link(SitesLink.Rel.TEMPLATE, Link.Type.ATOM, templateEntry.getSelfLink().getHref()));

FileCabinetPageEntry createdFileCabinetFromTemplate =  client.insert(feedUrl, templateInstanceEntry);

ملاحظة: على الرغم من وجود نموذج يحدد <category>، فإن تضمين واحد في لا يزال الدخول مطلوبًا. يُرجى العِلم أيضًا أنّ الخادم سيرفضه في حال تضمين عنصر <content>.

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

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

لتحميل مرفق إلى أحد الوالدَين، أرسِل طلب HTTP POST إلى عنوان URL لخلاصة المحتوى:

https://sites.google.com/feeds/content/site/siteName

يجب تحميل كل أنواع المرفقات إلى صفحة رئيسية. لذلك، يمكنك إعداد رابط رئيسي على AttachmentEntry. أو عنصر واحد (WebAttachmentEntry) تحاول تحميله. راجِع إنشاء صفحات فرعية للحصول على مزيد من المعلومات.

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

يتم في هذا المثال تحميل ملف PDF إلى أول FileCabinetPageEntry تم العثور عليه في خلاصة محتوى المستخدم. يتم إنشاء المرفق بعنوان "البدء". ووصف (اختياري)، "حزمة الموارد البشرية".

MimetypesFileTypeMap mediaTypes = new MimetypesFileTypeMap();
mediaTypes.addMimeTypes("application/msword doc");
mediaTypes.addMimeTypes("application/vnd.ms-excel xls");
mediaTypes.addMimeTypes("application/pdf pdf");
mediaTypes.addMimeTypes("text/richtext rtx");
// ... See a more complete list of mime types in the SitesHelper.java

public AttachmentEntry uploadAttachment(File file, BasePageEntry<?> parentPage,
    String title, String description) throws IOException, ServiceException {
  AttachmentEntry newAttachment = new AttachmentEntry();
  newAttachment.setMediaSource(new MediaFileSource(file, mediaTypes.getContentType(file)));
  newAttachment.setTitle(new PlainTextConstruct(title));
  newAttachment.setSummary(new PlainTextConstruct(description));
  newAttachment.addLink(SitesLink.Rel.PARENT, Link.Type.ATOM, parentPage.getSelfLink().getHref());

  return client.insert(new URL(buildContentFeedUrl()), newAttachment);
}

ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl() + "?kind=filecabinet"), ContentFeed.class);
FileCabinetPageEntry parentPage = contentFeed.getEntries(FileCabinetPageEntry.class).get(0);

AttachmentEntry attachment = uploadAttachment(
    new File("/path/to/your/file.pdf"), parentPage, "Getting Started", "HR packet");
System.out.println("Uploaded!");

إذا تم التحميل بنجاح، سيحتوي attachment على نسخة من إدخال المرفق الذي تم إنشاؤه.

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

لتحميل مرفق إلى مجلد حالي في FileCabinetPageEntry، يجب تضمين فئة باستخدام "العبارة". التي تم تعيينها على اسم المجلد. على سبيل المثال، أضِف هذا السطر في uploadAttachment():

newAttachment.getCategories().add(new Category("http://schemas.google.com/sites/2008#folder", "FolderName"));

مرفقات الويب

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

ملاحظة: لا يمكن إنشاء مرفقات الويب إلا ضمن خزانة ملفات. ولا يمكن تحميلها إلى أنواع أخرى من الصفحات.

ينشئ هذا المثال WebAttachmentEntry ضمن أول FileCabinetPageEntry تم العثور عليه في خلاصة محتوى المستخدم. تم ضبط عنوانه ووصفه (الاختياري) على "GoogleLogo". و"ألوان جميلة"، على التوالي.

public WebAttachmentEntry uploadWebAttachment(String contentUrl, FileCabinetPageEntry filecabinet,
    String title, String description) throws MalformedURLException, IOException, ServiceException {
  MediaContent content = new MediaContent();
  content.setUri(contentUrl);

  WebAttachmentEntry webAttachment = new WebAttachmentEntry();
  webAttachment.setTitle(new PlainTextConstruct(title));
  webAttachment.setSummary(new PlainTextConstruct(description));
  webAttachment.setContent(content);
  webAttachment.addLink(SitesLink.Rel.PARENT, Link.Type.ATOM,
      filecabinet.getSelfLink().getHref());

  return client.insert(new URL(buildContentFeedUrl()), webAttachment);
}

ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl() + "?kind=filecabinet"), ContentFeed.class);
FileCabinetPageEntry parentPage = contentFeed.getEntries(FileCabinetPageEntry.class).get(0);

WebAttachmentEntry webAttachment =
    uploadWebAttachment("http://www.google.com/images/logo.gif", parentPage, "Google's Logo", "nice colors");
System.out.println("Web attachment created!");

تنشئ POST رابطًا في صفحة خزانة ملفات المستخدم يشير إلى الصورة على "http://www.google.com/images/logo.gif".

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

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

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

يمكن تعديل البيانات الوصفية (العنوان واسم الصفحة وما إلى ذلك) ومحتوى الصفحة من أي نوع BaseContentEntry من خلال باستخدام طريقة update() للإدخال. سيؤدي ذلك إلى إرسال طلب HTTP PUT إلى عنصر edit الخاص بالإدخال. .

في ما يلي مثال على تعديل ListPageEntry بالتغييرات التالية:

تم تعديل العنوان إلى "العنوان المعدّل"
يتم تحديث محتوى HTML للصفحة إلى '<p>محتوى HTML المحدّث</p>'.
تم تغيير عنوان العمود الأول من القائمة إلى "المالك"

ContentFeed contentFeed = client.getFeed(
    new URL(buildContentFeedUrl() + "?kind=listpage"), ContentFeed.class);
ListPageEntry listPage = contentFeed.getEntries(ListPageEntry.class).get(0); // Update first list page found

// Update title
listPage.setTitle(new PlainTextConstruct("Updated Title"));

// Update HTML content
XmlBlob xml = new XmlBlob();
xml.setBlob("<p>Updated HTML Content</p>");
listPage.setContent(new XhtmlTextConstruct(xml));

// Change first column's heading
listPage.getData().getColumns().get(0).setName("Owner");

// listPage.setPageName(new PageName("new-page-path"));  // You can also change the page's URL path

ListPageEntry updatedEntry = listPage.update();

System.out.println("ListPage updated!");

تعديل محتوى الملف المُرفق

بالنسبة إلى AttachmentEntry، يمكنك أيضًا تعديل المحتوى من خلال ضبط الإدخال MediaSource ثم استخدام طريقة updateMedia(boolean) للإدخال.

سيعدّل هذا المثال محتوى مرفق حالي:

public AttachmentEntry updateFile(AttachmentEntry entry, File newFile)
    throws IOException, ServiceException {
  // See Uploading Attachments for the definition of mediaTypes.
  entry.setMediaSource(new MediaFileSource(newFile, mediaTypes.getContentType(newFile)));
  return entry.updateMedia(false);
}

يرسل المثال طلب HTTP PUT إلى رابط edit-media الخاص بالإدخال. تم إرجاع سيحتوي AttachmentEntry على المحتوى الذي تم تعديله.

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

يمكنك تعديل البيانات الوصفية للمرفق ومحتواه في المكالمة نفسها باستخدام طريقة updateMedia(). إذا كان بإمكانك تعديل محتوى الملف فقط أو البيانات الوصفية أو كليهما.

يغيّر هذا المثال عنوان المرفق إلى "عنوان جديد" ويعدّل وصفه ويستبدل محتوى الملف بملف ZIP جديد. بما أنّ الطلب يتضمّن محتوى ملف جديدًا، يتم استخدام updateMedia() في AttachmentEntry.

public AttachmentEntry updateAttachment(AttachmentEntry entry, File newFile, String newTitle, String newDescription)
    throws IOException, ServiceException  {
  // See Uploading Attachments for the definition of mediaTypes.
  entry.setMediaSource(new MediaFileSource(newFile, mediaTypes.getContentType(newFile)));
  entry.setTitle(new PlainTextConstruct(newTitle));
  entry.setSummary(new PlainTextConstruct(newDescription));

  return entry.updateMedia(true);
}

ContentFeed contentFeed = client.getFeed(
    new URL(buildContentFeedUrl() + "?kind=attachment&max-results=1"), ContentFeed.class);
AttachmentEntry attachment = contentFeed.getEntries(AttachmentEntry.class).get(0); // Update first attachment found

AttachmentEntry updatedAttachment = updateAttachment(attachment, new File("/path/to/file.zip"), "New Title", "better stuff");

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

حذف المحتوى

لإزالة صفحة أو عنصر من موقع مصمم في "مواقع Google"، عليك أولاً استرداد إدخال المحتوى، ثم طلب delete() الخاصة بالإدخال.

entry.delete();

يمكنك أيضًا استخدام طريقة delete() لفئة الخدمة من خلال إدخال رابط edit للإدخال وقيمة ETag التالية:

client.delete(entry.getEditLink().getHref(), "*"); // Note: using "*" may overwrite another client's changes.

وإذا تم حذف الإدخال بنجاح، يستجيب الخادم باستخدام 200 OK HTTP.

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

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

لتنزيل AttachmentEntry، أرسِل طلب HTTP يتضمّن GET إلى رابط src الخاصة بمحتوى الإدخال.

يؤدي هذا المثال إلى تنزيل أول AttachmentEntry عنصر تم العثور عليه في خلاصة محتوى المستخدم. إلى الدليل "/path/to/save/file/":

private void downloadFile(String downloadUrl, String fullFilePath) throws IOException, ServiceException {
  System.out.println("Downloading file from: " + downloadUrl);

  MediaContent mc = new MediaContent();
  mc.setUri(downloadUrl);
  MediaSource ms = service.getMedia(mc);

  InputStream inStream = null;
  FileOutputStream outStream = null;

  try {
    inStream = ms.getInputStream();
    outStream = new FileOutputStream(fullFilePath);

    int c;
    while ((c = inStream.read()) != -1) {
      outStream.write(c);
    }
  } finally {
    if (inStream != null) {
      inStream.close();
    }
    if (outStream != null) {
      outStream.flush();
      outStream.close();
    }
  }
}

public void downloadAttachment(AttachmentEntry entry, String directory) throws IOException, ServiceException {
  String url = ((OutOfLineContent) entry.getContent()).getUri();
  downloadFile(url, directory + entry.getTitle().getPlainText()); // Use entry's title for the save filename
}

ContentFeed contentFeed = client.getFeed(
    new URL(buildContentFeedUrl() + "?kind=attachment&max-results=1"), ContentFeed.class);

downloadAttachment(contentFeed.getEntries(AttachmentEntry.class).get(0), "/path/to/save/file/");
System.out.println("Downloaded.");

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

موجز 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)

يمكن استخدام الصفَّين AclFeed وAclEntry للتحكّم في مشاركة الموقع الإلكتروني. ويمكن جلبها باستخدام طريقة getFeed() لفئة الخدمة.

يجلب المثال التالي خلاصة قائمة التحكم بالوصول (ACL) لموقع معين ويطبع أذونات كل AclEntry:

public String getAclFeedUrl(String siteName) {
  String domain = "site";  // OR if the Site is hosted on G Suite, your domain (e.g. example.com)
  return "https://sites.google.com/feeds/acl/site/" + domain + "/" + siteName + "/";
}

public void getAclFeed(String siteName) throws IOException, ServiceException {
  AclFeed aclFeed = client.getFeed(new URL(getAclFeedUrl(siteName)), AclFeed.class);
  for (AclEntry entry : aclFeed.getEntries()) {
    System.out.println(entry.getScope().getValue() + " (" + entry.getScope().getType() + ") : " +
                       entry.getRole().getValue());
  }
}

getAclFeed('my-site-name');

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

String aclLink = siteEntry.getLink(SitesAclFeedLink.Rel.ACCESS_CONTROL_LIST, Link.Type.ATOM).getHref();
AclFeed aclFeed = client.getFeed(new URL(aclLink), AclFeed.class);

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

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

لمشاركة موقع مصمم في مواقع Google باستخدام واجهة برمجة التطبيقات، يجب على العميل إنشاء موقع جديد AclEntry وPOST إلى الخادم.

وفي ما يلي مثال يضيف "user@example.com" بصفتك reader على الموقع الإلكتروني:

AclRole role = new AclRole("reader");
AclScope scope = new AclScope(AclScope.Type.USER, "user@example.com");
AclEntry aclEntry = addAclRole(role, scope, entry);

public AclEntry addAclRole(AclRole role, AclScope scope, SiteEntry siteEntry)
    throws IOException, MalformedURLException, ServiceException  {
  AclEntry aclEntry = new AclEntry();
  aclEntry.setRole(role);
  aclEntry.setScope(scope);

  Link aclLink = siteEntry.getLink(SitesAclFeedLink.Rel.ACCESS_CONTROL_LIST, Link.Type.ATOM);
  return client.insert(new URL(aclLink.getHref()), aclEntry);
}

راجِع قسم نظرة عامة على خلاصة ACL لمعرفة AclScope الممكنة. وقيم AclRoles.

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

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

المشاركة مع عنوان بريد إلكتروني لمجموعة:

AclScope scope = new AclScope(AclScope.Type.GROUP, "group_name@example.com");

المشاركة مع نطاق كامل:

AclScope scope = new AclScope(AclScope.Type.DOMAIN, "example.com");

لا تتوفّر المشاركة على مستوى النطاق إلا لنطاقات G Suite، وللنطاق الذي يستضيف الموقع الإلكتروني فقط. على سبيل المثال، يمكن للموقع http://sites.google.com/a/domain1.com/siteA مشاركة الموقع بالكامل مع domain1.com فقط، وليس domain2.com. المواقع التي لا تتم استضافتها على نطاق G Suite (على سبيل المثال، لا يمكن لـ http://sites.google.com/site/siteB) دعوة نطاقات.

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

للحصول على إذن مشاركة حالي على موقع إلكتروني، عليك أولاً جلب AclEntry المعنيّ، وتعديل الإذن. على النحو المطلوب، ثم يمكنك استدعاء طريقة update() في AclEntry لتعديل قائمة التحكم بالوصول (ACL) على الخادم.

يعدّل هذا المثال مثال aclEntry السابق من قسم مشاركة الموقع الإلكتروني، من خلال تحديث "user@example.com" أن تكون writer (متعاونًا):

aclEntry.setRole(new AclRole("writer"));
AclEntry updatedAclEntry = aclEntry.update();

// Could also use the client's update method
// client.update(new URL(aclEntry.getEditLink().getHref()), aclEntry);

لمزيد من المعلومات عن علامات ETags، اطلع على الدليل المرجعي لواجهات Google Data APIs.

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

لإزالة إذن مشاركة، عليك أولاً استرداد AclEntry، ثم طلب طريقة delete() الخاصة به:

aclEntry.delete();

// Could also use the client's delete method
// client.delete(new URL(aclEntry.getEditLink().getHref()), aclEntry);

لمزيد من المعلومات عن علامات ETags، اطلع على الدليل المرجعي لواجهات Google Data APIs.

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

مواضيع خاصة

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

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

لإجراء هذا النوع من الاسترجاع المشروط، توفر كل من الطريقتين getFeed() وgetEntry() وسيطة إضافية تقبل قيمة ETag أو كائن DateTime لرأس If-Modified-Since. يمكنك الوصول إلى علامة etag لأحد الإدخالات من خلال تطبيق entry.getEtag().

يُجري هذا المثال استرجاعًا مشروطًا لإدخال صفحة ويب محتوى:

String feedUrl = "https://sites.google.com/feeds/content/site/siteName/123456789";
WebPageEntry entry = client.getEntry(new URL(feedUrl), WebPageEntry.class, "\"GVQHSARDQyp7ImBq\"");

عندما يتلقى الخادم هذا الطلب، يتحقق لمعرفة ما إذا كان العنصر الذي طلبته يحتوي على علامة ETag نفسها كما في علامة ETag التي حددتها. إذا تطابقت علامات ETag، فهذا يعني أن العنصر لم يتغير، ويعرض الخادم إما سيتم طرح استثناء HTTP 304 NotModifiedException.

إذا لم تتطابق علامات ETag، فهذا يعني أنه تم تعديل العنصر منذ آخر مرة طلبته فيها، ويعيد الخادم العنصر.

لمزيد من المعلومات عن علامات ETags، اطلع على الدليل المرجعي لواجهات Google Data APIs.

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

دليل لغة Java

الجمهور

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

تثبيت المكتبة

تشغيل نموذج التطبيق

بدء مشروعك الخاص

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

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

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

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

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

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

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

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

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

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

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

خلاصة الموقع

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

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

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

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

تعيينات عناوين الويب

جارٍ استرجاع عمليات ربط عناوين الويب لأحد المواقع الإلكترونية

تعديل تعيينات عناوين الويب

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

خلاصة المراجعات

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

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

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

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

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

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

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

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

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

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

نماذج الصفحات

إنشاء نماذج الصفحات

إنشاء صفحات من نموذج

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

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

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

مرفقات الويب

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

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

تعديل محتوى الملف المُرفق

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

حذف المحتوى

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

موجز ACL

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

الأدوار

المستويات

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

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

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

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

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

مواضيع خاصة

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