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

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

دليل لغة Java

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

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

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

الجمهور

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

البدء

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

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

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

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

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

java/lib/gdata-sites-2.0.jar - الإصدار 2.0 هنا مخصّص للإصدار 1.4 من واجهة برمجة تطبيقات المواقع الكلاسيكية.
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 للمستخدم بإجراء عدد من العمليات التي توضح كيفية استخدام واجهة برمجة تطبيقات المواقع الكلاسيكية.

ملاحظة: يجب تضمين java/sample/util/lib/sample-util.jar لتشغيل النموذج.

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

ملاحظة: راجِع مقالة استخدام Eclipse مع واجهات برمجة التطبيقات لبيانات Google لإعداد سريع باستخدام مكوّن 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، والذي يمثّل اتصال العميل بواجهة برمجة تطبيقات المواقع الكلاسيكية:

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

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

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

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

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

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

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

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

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

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

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

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

import com.google.gdata.client.*;

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

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

import com.google.gdata.client.*;

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

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

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

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

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

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

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

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

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

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

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

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

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 Client Libraries.

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

خلاصة الموقع

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

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

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

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

في عميل Java، يمكنك استخدام الفئتين SiteFeed وSiteEntry للعمل مع خلاصة الموقع الإلكتروني:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نقاط مهمة:

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

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

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

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

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

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

SiteEntry updatedSiteEntry = myTwin.update();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لإجراء طلب بحث في خلاصة النشاط، أرسِل GET HTTP إلى عنوان 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());
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لمعرفة المزيد من المَعلمات، اطّلِع على الدليل المرجعي.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

إنشاء صفحات من قالب

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

يؤدي هذا المثال إلى إنشاء نموذج filecabinet جديد، ثم إنشاء مثيل لصفحة filecabinet جديدة من ذلك النموذج.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مرفقات الويب

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ListPageEntry updatedEntry = listPage.update();

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

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

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

سيؤدي هذا المثال إلى تحديث محتوى أي مرفق موجود:

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

يرسل المثال طلب HTTP PUT إلى رابط edit-media للإدخال. سيتضمّن العنصر AttachmentEntry المعروض المحتوى المعدَّل.

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

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

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

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

  return entry.updateMedia(true);
}

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

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

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

حذف المحتوى

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

entry.delete();

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

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

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

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

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

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

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

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

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

  InputStream inStream = null;
  FileOutputStream outStream = null;

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

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

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

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

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

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

خلاصة ACL

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

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

الأدوار

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

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

المستويات

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

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

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

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

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

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

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

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

aclEntry.delete();

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

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

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

مواضيع خاصة

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

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

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

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

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

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

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

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

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

دليل لغة Java

الجمهور

البدء

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

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

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

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

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

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

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

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

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

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

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

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

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

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

خلاصة الموقع

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

إنشاء صفحات من قالب

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

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

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

مرفقات الويب

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

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

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

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

حذف المحتوى

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

خلاصة ACL

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

الأدوار

المستويات

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

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

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

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

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

مواضيع خاصة

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