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

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

دليل لغة Java

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

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

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

الجمهور

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

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

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

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

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

تثبيت Java 1.5 أو إصدار أحدث
تنزيل مكتبة البرامج (أحدث إصدار من 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 (في حالة العمل مع صفحات القائمة / عناصر القوائم)

تأكَّد أيضًا من تضمين حاويات التبعية (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 Data APIs للحصول على مزيد من المعلومات عن AuthSub وOAuth وClientLogin.

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

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

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

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

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

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

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

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

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

مرفقات الويب

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

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

وإذا تم حذف الإدخال بنجاح، يستجيب الخادم باستخدام 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)

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

الأدوار

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

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

المستويات

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

user — قيمة عنوان بريد إلكتروني، مثل "user@gmail.com".
المجموعة: عنوان بريد إلكتروني في "مجموعات Google"، مثل "المجموعة@النطاق.com".
النطاق: اسم نطاق G Suite، مثل "domain.com".
default: هناك نطاق واحد فقط من النوع "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، يعني ذلك أنّ العنصر لم يتغيّر، وسيعرض الخادم إما علامة NotModifiedException أو استثناء HTTP 304.

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

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

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

دليل لغة Java

الجمهور

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مرفقات الويب

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

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

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

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

حذف المحتوى

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

خلاصة ACL

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

الأدوار

المستويات

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

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

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

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

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

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

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