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

دليل لغة Java

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

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

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

الجمهور

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

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

تستخدِم "مواقع Google" حسابات Google أو حسابات G Suite للمصادقة. إذا كان لديك حساب، لست بحاجة إلى اتخاذ أي إجراءات إضافية. بخلاف ذلك، يمكنك إنشاء حساب جديد.

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

للحصول على مساعدة في إعداد مكتبة البرامج وتثبيتها، يُرجى الاطّلاع على بدء استخدام مكتبة برامج Google Data Java. إذا كنت تستخدم 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 من Sites API الكلاسيكية.
java/lib/gdata-core-1.0.jar
java/lib/gdata-client-1.0.jar
java/lib/gdata-spreadsheet-3.0.jar (في حال العمل مع صفحات القوائم / عناصر القوائم)

احرص أيضًا على تضمين ملفات 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 للمستخدم تنفيذ عدد من العمليات التي توضّح كيفية استخدام Sites API الكلاسيكية.

يُرجى العِلم أنّه عليك تضمين 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.

المصادقة على Sites API للإصدار الكلاسيكي من "مواقع Google"

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

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

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

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

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

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

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

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

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

ملاحظة: تتوفّر هذه الميزة لنطاقات 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".

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

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

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

تعرض خلاصة المحتوى أحدث محتوى في الموقع الإلكتروني. يمكن الوصول إلى هذه الخلاصة من خلال إرسال GET HTTP إلى عنوان 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 وتلك الخاصة بواجهة Sites API الكلاسيكية. للحصول على معلومات أكثر تفصيلاً وقائمة كاملة بالمعلَمات المتوافقة، يُرجى الاطّلاع على دليل المراجع.

ملاحظة: تستخدم الأمثلة الواردة في هذا القسم طريقة 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>، يجب تضمين <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، أدرِج فئة مع ضبط السمة "term" على اسم المجلد. على سبيل المثال، أضِف هذا السطر في uploadAttachment():

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

مرفقات الويب

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

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

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

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>Updated HTML Content</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.

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

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

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

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

الأدوار

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

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

المستويات

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

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

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

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

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

يجلب المثال التالي خلاصة قائمة التحكم في الوصول لموقع إلكتروني معيّن، ويطبع أذونات كل 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 على رابط إلى خلاصة قائمة التحكّم بالوصول. على سبيل المثال، يسترد هذا المقتطف خلاصة قائمة التحكّم بالوصول الخاصة بـ SiteEntry:

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

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

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

راجِع قسم نظرة عامة على خلاصة قائمة التحكّم بالوصول للاطّلاع على القيم المحتمَلة 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 لتعديل قائمة التحكّم بالوصول على الخادم.

يعدّل هذا المثال مثال 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);

لمزيد من المعلومات عن علامات ETag، يُرجى الاطّلاع على دليل مراجع Google Data APIs.

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

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

aclEntry.delete();

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

لمزيد من المعلومات عن علامات ETag، يُرجى الاطّلاع على دليل مراجع 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 نفسها التي حدّدتها. إذا تطابقت قيم ETags، يعني ذلك أنّ العنصر لم يتغيّر، وسيعرض الخادم إما استثناء HTTP 304 NotModifiedException.

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

لمزيد من المعلومات عن علامات ETag، يُرجى الاطّلاع على دليل مراجع Google Data APIs.

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

دليل لغة Java تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الجمهور

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

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

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

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

المصادقة على Sites API للإصدار الكلاسيكي من "مواقع Google"

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

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

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

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

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

OAuth لتطبيقات الويب أو التطبيقات المثبَّتة/المتوافقة مع الأجهزة الجوّالة

جلب رمز مميّز للطلب

منح الإذن باستخدام رمز الطلب

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

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

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

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

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

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

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

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

استرداد عمليات ربط عناوين الويب لموقع إلكتروني

تعديل عمليات ربط عناوين الويب

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تحميل الملفات

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

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

مرفقات الويب

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

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

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

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

حذف المحتوى

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

خلاصة قائمة التحكم بالوصول

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

الأدوار

المستويات

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

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

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

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

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

مواضيع خاصة

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

دليل لغة Java