Руководство по языку Java

Важно! Этот документ был написан до 2012 г. Варианты аутентификации, описанные в этом документе (OAuth 1.0, AuthSub и ClientLogin), официально устарели с 20 апреля 2012 г. и больше не поддерживаются. Мы рекомендуем вам как можно скорее перейти на OAuth 2.0.

Google Sites Data API позволяет клиентским приложениям получать доступ к контенту на сайте Google, публиковать его и изменять. Клиентское приложение также может запрашивать список недавних действий, получать историю изменений и скачивать прикрепленные файлы.

В этом руководстве не только рассказывается о возможностях Sites Data API, но и приводятся примеры взаимодействия с API с помощью клиентской библиотеки Java. Инструкции по настройке клиентской библиотеки можно найти в статье Как начать работу с клиентской библиотекой Google Data для Java. Если вы хотите узнать больше о протоколе, который используется клиентской библиотекой Java для взаимодействия с классическим Sites API, ознакомьтесь с руководством по протоколу.

Аудитория

Этот документ предназначен для разработчиков, которые хотят создавать клиентские приложения, взаимодействующие с Google Сайтами с помощью клиентской библиотеки Google Data для Java.

Начало работы

Для аутентификации в Google Сайтах используются аккаунты Google или G Suite. Если он у вас уже есть, никаких дополнительных действий не требуется. В противном случае вы можете создать новый аккаунт.

Установка библиотеки

Инструкции по настройке и установке клиентской библиотеки можно найти в руководстве по началу работы с клиентской библиотекой Google Data для Java. Если вы используете Eclipse, в этой статье также рассказывается, как настроить проект с помощью плагина Google Data APIs для Eclipse. Чтобы начать, вам понадобится:

1. Установите Java 1.5 или более поздней версии
2. Скачайте клиентскую библиотеку (последнюю версию gdata-src.java.zip).
3. Скачайте список зависимостей.
4. Скачайте примеры приложений (последняя версия gdata-samples.java.zip).

После установки JAR-файлов вам нужно будет добавить в проект следующие элементы:

1. java/lib/gdata-sites-2.0.jar – версия 2.0 здесь относится к версии 1.4 классического Sites API.
2. java/lib/gdata-core-1.0.jar
3. java/lib/gdata-client-1.0.jar
4. java/lib/gdata-spreadsheet-3.0.jar (если вы работаете со страницами списков или элементами списков)

Также добавьте файлы JAR зависимостей (gdata-media-1.0.jar, mail.jar и google-collect....jar).

Как запустить пример приложения

Полностью рабочий пример приложения находится в подкаталоге /java/sample/sites скачанного файла gdata-samples.java.zip. Исходный код также доступен в репозитории SVN по адресу /trunk/java/sample/sites/. SitesDemo.java позволяет пользователю выполнять различные операции, демонстрирующие, как использовать классический Sites API.

Примечание. Чтобы запустить пример, вам нужно будет добавить java/sample/util/lib/sample-util.jar.

Как начать собственный проект

Совет. Чтобы быстро настроить плагин Eclipse, ознакомьтесь со статьей Как использовать Eclipse с Google Data API.

В зависимости от потребностей приложения вам потребуется несколько импортов. Рекомендуем начать со следующих импортов:

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, который представляет собой клиентское подключение к классическому API Сайтов:

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

Аргумент applicationName должен иметь формат company-applicationname-version. Этот параметр используется для ведения журналов.

Примечание. В остальной части этого руководства предполагается, что вы создали SitesService в переменной client.

Как выполнять аутентификацию для Sites API

Клиентскую библиотеку Java можно использовать для работы с общедоступными и частными фидами. Sites Data API предоставляет доступ к частным и общедоступным фидам в зависимости от разрешений Сайтов и операции, которую вы пытаетесь выполнить. Например, вы можете читать фид контента общедоступного сайта, но не сможете его изменить, так как для этого требуется аутентифицированный клиент. Это можно сделать с помощью аутентификации по имени пользователя и паролю ClientLogin, AuthSub или OAuth.

Подробнее об аутентификации в API данных Google…

Совет. API поддерживает SSL (HTTPS). Если вы используете AuthSub/OAuth, обязательно укажите область действия https://sites.google.com/feeds/, чтобы запрашивать фиды через SSL. Обратите внимание, что для доменов G Suite API учитывает параметр "Требовать SSL" на панели управления администратора. Вы можете принудительно использовать HTTPS для всех запросов API, вызвав client.useSsl();.

AuthSub для веб-приложений

Аутентификация AuthSub для веб-приложений должна использоваться клиентскими приложениями, которым необходимо аутентифицировать пользователей в аккаунтах Google. Оператору не нужен доступ к имени пользователя и паролю пользователя Google Сайтов – требуется только токен AuthSub.

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);

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);

OAuth для веб-приложений или установленных/мобильных приложений

OAuth можно использовать вместо AuthSub. Этот протокол предназначен для веб-приложений. OAuth похож на защищенный зарегистрированный режим AuthSub, поскольку все запросы данных должны быть подписаны цифровой подписью, а домен необходимо зарегистрировать.

ClientLogin для установленных и мобильных приложений

ClientLogin следует использовать в установленных или мобильных приложениях, которым необходимо аутентифицировать пользователей в аккаунтах Google. При первом запуске приложение запрашивает у пользователя имя и пароль. В последующих запросах указывается токен аутентификации.

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

К началу

Фид сайта

Фид сайтов можно использовать для создания списка сайтов Google, которыми владеет пользователь или которые ему разрешено просматривать. Его также можно использовать, чтобы изменить название существующего сайта. В доменах G Suite его также можно использовать для создания и/или копирования целых сайтов.

Сайты с предложениями

Чтобы запросить фид сайта, отправьте HTTP-запрос GET на URL фида сайта:

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

В клиенте Java для работы с фидом сайта можно использовать классы SiteFeed и SiteEntry:

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

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

Приведенный выше фрагмент кода выводит название сайта, его имя и тему. Для доступа к другим свойствам фида можно использовать другие методы получения.

Создание новых сайтов

Примечание. Эта функция доступна только в доменах G Suite.

Новые сайты можно создавать, создавая новый объект SiteEntry и вызывая метод insert() клиента в фиде сайта.

В этом примере создается новый сайт с темой "сланец" (необязательный параметр), а также указывается название сайта (обязательный параметр) и описание (необязательный параметр):

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. Например, вместо http://sites.google.com/a/domain.com/mysite можно использовать http://www.mydomainsite.com. В зависимости от того, где размещен ваш сайт, вы можете вручную изменить сопоставления веб-адресов. Подробнее об этом можно узнать в Справочном центре.

Как получить сопоставления веб-адресов сайта

Чтобы получить сопоставления веб-адресов для сайта, запросите запись или фид сайта с параметром 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. Если параметр отсутствует, значение webAddressMappings не будет возвращаться в записях сайта (GET) или учитываться при обновлении/удалении (PUT) сопоставлений из записи.

Чтобы добавить, изменить или удалить сопоставление, укажите, измените или удалите ссылку при создании нового сайта или обновлении метаданных сайта. Параметр with-mappings=true должен быть включен в URI фида сайта. Примечание. Чтобы изменить сопоставления адресов, вам нужны права администратора сайта или администратора домена, если сайт размещен в G Suite.

Например, в приведенном ниже запросе сопоставление http://www.mysitemapping.com обновляется до http://www.my-new-sitemapping.com, а сопоставление http://www.mysitemapping2.com удаляется, поскольку ссылка на него отсутствует в записи:

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

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

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

Обратите внимание, что сопоставления веб-адресов также можно указать при создании или копировании сайта.

К началу

Фид действий

Чтобы получить информацию о недавних действиях на сайте (изменениях), запросите фид действий. Каждая запись в фиде действий содержит информацию об изменении, внесенном на сайт.

Чтобы запросить фид действий, отправьте HTTP-запрос GET на URL фида действий:

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

В клиенте Java используйте класс ActivityFeed, чтобы возвращать объекты ActivityEntry:

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

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

Примечание. Чтобы получить доступ к этому фиду, вы должны быть соавтором или владельцем сайта. Клиент должен пройти аутентификацию с помощью токена AuthSub, OAuth или ClientLogin. Подробнее о том, как пройти аутентификацию в сервисе "Сайты"…

К началу

Фид изменений

Чтобы получить историю изменений для любого контента, отправьте 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. Подробнее о том, как пройти аутентификацию в сервисе "Сайты"…

К началу

Фид

Получение фида контента

В фиде контента перечислены последние материалы сайта. Чтобы получить доступ к этому файлу, отправьте HTTP-запрос GET на URL фида контента:

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

Пример запроса фида контента:

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 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 страницы сервер использует следующие правила приоритета:

1. <sites:pageName>, если есть. Должно соответствовать a-z, A-Z, 0-9, -, _.
2. <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 Сайтах, API поддерживает загрузку прикрепленных файлов на страницу типа "картотека" или родительскую страницу.

Чтобы загрузить прикрепленный файл в родительский объект, отправьте 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, найденным в фиде контента пользователя. Его название и описание (необязательно) – "GoogleLogo" и "nice colors" соответственно.

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

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

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

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

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

Тег POST создает в файловом хранилище пользователя ссылку на изображение по адресу http://www.google.com/images/logo.gif.

К началу

Обновление контента

Изменение метаданных и/или HTML-контента страницы

Метаданные (заголовок, название страницы и т. д.) и контент страницы любого типа BaseContentEntry можно изменить с помощью метода update(). Это отправит HTTP-запрос PUT по ссылке edit записи.

Ниже приведен пример того, как обновить ListPageEntry, внеся следующие изменения:

• Название изменено на "Новое название".
• HTML-контент страницы обновляется до "<p>Updated HTML Content</p>".
• Первый столбец списка теперь называется "Владелец".

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

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

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

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

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

ListPageEntry updatedEntry = listPage.update();

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

Обновление содержимого прикрепленного файла

Для AttachmentEntry вы также можете обновить контент, задав значение MediaSource для записи, а затем используя метод updateMedia(boolean) для этой записи.

В этом примере показано, как обновить контент существующего прикрепленного файла:

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

В примере отправляется HTTP-запрос PUT по ссылке edit-media записи. Возвращенный объект AttachmentEntry будет содержать обновленный контент.

Как обновить метаданные и контент прикрепленного файла

Вы можете обновить метаданные и контент прикрепленного файла в одном вызове, используя метод updateMedia(). Если вы можете обновить только контент файла, метаданные или и то, и другое.

В этом примере показано, как изменить название прикрепленного файла на "Новое название", обновить его описание и заменить содержимое новым ZIP-файлом. Поскольку запрос содержит новый контент файла, используется updateMedia() организации AttachmentEntry.

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

  return entry.updateMedia(true);
}

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

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

К началу

Удаление контента

Чтобы удалить страницу или элемент с сайта Google, сначала получите запись контента, а затем вызовите delete() записи.

entry.delete();

Вы также можете использовать метод delete() класса сервиса, передав ему ссылку edit записи и значение ETag:

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

Если запись была успешно удалена, сервер отвечает кодом HTTP 200 OK.

К началу

Как скачать прикрепленные файлы

Чтобы скачать AttachmentEntry, отправьте HTTP-запрос GET по ссылке на источник контента записи.

В этом примере первое изображение 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

Обзор разрешений на предоставление доступа (списков контроля доступа)

Каждая запись в фиде ACL представляет роль доступа определенного объекта: пользователя, группы пользователей, домена или доступа по умолчанию (общедоступного сайта). Записи будут показываться только для объектов с явным доступом – по одной записи для каждого адреса электронной почты на панели "Пользователи с доступом" на экране предоставления доступа в интерфейсе Google Сайтов. Поэтому администраторы домена не будут показаны, даже если у них есть неявный доступ к сайту.

Роли

Элемент role представляет уровень доступа, который может быть у объекта. Элемент gAcl:role может принимать четыре значения:

• Читатель – пользователь с правами просмотра (эквивалент доступа только для чтения).
• writer – соавтор (эквивалент доступа для чтения и записи).
• Владелец – обычно администратор сайта (эквивалентно доступу на чтение и запись).

Области действия

Элемент области действия представляет объект, которому назначен этот уровень доступа. Существует четыре возможных типа элемента gAcl:scope:

• user – значение адреса электронной почты, например user@gmail.com.
• group – адрес электронной почты группы Google, например group@domain.com.
• domain – доменное имя 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 с помощью API, клиент должен создать новый объект AclEntry и POST его на сервер.

Вот пример того, как добавить адрес электронной почты user@example.com в качестве элемента reader на сайте:

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

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

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

Возможные значения AclScope и AclRoles приведены в разделе Обзор фида ACL.

Предоставление доступа на уровне группы и домена

Как и в случае с предоставлением доступа к сайту одному пользователю, вы можете предоставить доступ к сайту группе Google или домену G Suite.

Предоставление доступа к электронному адресу группы:

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

Предоставление доступа всему домену:

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

Предоставление доступа на уровне домена поддерживается только для доменов G Suite и только для домена, на котором размещен сайт. Например, сайт http://sites.google.com/a/domain1.com/siteA можно предоставить только домену domain1.com, но не domain2.com. Сайты, которые не размещены в домене G Suite (например, http://sites.google.com/site/siteB), не могут приглашать домены.

Как изменить настройки доступа

Чтобы изменить существующее разрешение на доступ к сайту, сначала получите нужный объект AclEntry, измените разрешение, а затем вызовите метод update() объекта AclEntry, чтобы изменить список контроля доступа на сервере.

В этом примере мы изменили предыдущий пример с разметкой типа aclEntry из раздела Как поделиться сайтом, заменив user@example.com на writer (соавтор):

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

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

Подробнее о тегах ETag…

Как отменить разрешения на доступ

Чтобы удалить разрешение на доступ, сначала получите объект AclEntry, а затем вызовите его метод delete():

aclEntry.delete();

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

Подробнее о тегах ETag…

К началу

Специальные темы

повторно получить фид или запись;

Если вы хотите получить фид или запись, которые уже получали ранее, можно повысить эффективность, указав серверу отправлять список или запись только в том случае, если они изменились с момента последнего получения.

Для условного получения данных методы getFeed() и getEntry() предоставляют дополнительный аргумент, который принимает значение ETag или объект DateTime для заголовка If-Modified-Since. Получить доступ к тегу etag записи можно из entry.getEtag().

В этом примере показано, как выполнить условное получение записи веб-страницы с контентом:

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

Когда сервер получает этот запрос, он проверяет, совпадает ли ETag запрошенного объекта с ETag, который вы указали. Если теги ETag совпадают, значит объект не изменился, и сервер возвращает исключение HTTP 304 NotModifiedException.

Если теги ETag не совпадают, значит объект был изменен с момента последнего запроса, и сервер возвращает объект.

Подробнее о тегах ETag…

К началу