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

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

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

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

Аудитория

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

Начиная

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

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

Для получения помощи по настройке и установке клиентской библиотеки см. раздел Начало работы с клиентской библиотекой Google Data Java . Если вы используете Eclipse, в этой статье также объясняется, как настроить проект с помощью плагина Eclipse API данных Google . Вот что вам нужно для начала:

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

После установки .jars вам необходимо включить в свой проект следующее:

1. java/lib/gdata-sites-2.0.jar – версия 2.0 предназначена для версии 1.4 классического 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 . Исходный код также доступен по адресу /trunk/java/sample/sites/ в репозитории SVN, доступном на вкладке «Источник». SitesDemo.java позволяет пользователю выполнять ряд операций, демонстрирующих использование классического API Сайтов.

Обратите внимание: для запуска примера вам потребуется включить java/sample/util/lib/sample-util.jar .

Запуск собственного проекта

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

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

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

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

Аутентификация в классическом API Сайтов

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

Дополнительную информацию об AuthSub, OAuth и ClientLogin см. в обзоре аутентификации API данных Google .

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

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

Аутентификация AuthSub для веб-приложений должна использоваться клиентскими приложениями, которым необходимо аутентифицировать своих пользователей в учетных записях Google. Оператору не требуется доступ к логину и паролю пользователя Google Sites — требуется только токен 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 при работе с сопоставлениями веб-адресов. Если параметр отсутствует, значения webAddressMapping не будут возвращаться в записях сайта (GET) или учитываться при обновлении/удалении сопоставлений (PUT) из записи.

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

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

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

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

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

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

Вернуться наверх

Лента активности

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

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

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

В клиенте Java используйте класс ActivityFeed для возврата объектов ActivityEntry :

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

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

Примечание . Для доступа к этому каналу требуется, чтобы вы были соавтором или владельцем Сайта. Ваш клиент должен пройти аутентификацию с использованием токена AuthSub, OAuth или ClientLogin. См. раздел Аутентификация в службе Сайтов .

Вернуться наверх

Фид редакций

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

Примеры запросов к фиду контента

Вы можете выполнять поиск по ленте контента, используя некоторые стандартные параметры запроса API данных Google, а также параметры, специфичные для классического 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 . 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> , если присутствует. Должно удовлетворять az, AZ, 0-9, -, _ .
2. <atom:title> не должно быть нулевым, если имя страницы отсутствует. Нормализация заключается в обрезке + свертывании пробелов до '-' и удалении символов, не соответствующих az, AZ, 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». ' и 'шаблон' соответственно.

В этом примере создается новый шаблон 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 найденный в канале контента пользователя. Вложение создается с заголовком «Начало работы» и (необязательным) описанием «Пакет HR».

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.

Если запись была успешно удалена, сервер отвечает 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)

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

Роли

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

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

Области применения

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

• user — значение адреса электронной почты, например «user@gmail.com».
• группа — адрес электронной почты группы Google, например «group@domain.com».
• Домен — доменное имя G Suite, например «domain.com».
• default — существует только одна возможная область типа «default», которая не имеет значения (например <gAcl:scope type="default"> ). Эта конкретная область контролирует доступ, который любой пользователь имеет по умолчанию на общедоступном сайте.

Примечание . Домены не могут иметь значение gAcl:role установленное на доступ «владелец», они могут быть только читателями или писателями.

Получение канала 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);

Совместное использование сайта

Примечание . Некоторые списки управления доступом могут быть возможны только в том случае, если домен настроен на разрешение таких разрешений (например, если включен общий доступ за пределами домена для доменов 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 может совместно использовать весь сайт только с доменом 1.com, а не с доменом 2.com. Сайты, которые не размещены в домене G Suite (например, http://sites.google.com/site/siteB), не могут приглашать домены.

Изменение разрешений на общий доступ

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

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

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

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

Дополнительную информацию об ETags см. в справочном руководстве по API данных Google .

Удаление разрешений на общий доступ

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

aclEntry.delete();

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

Дополнительную информацию об ETags см. в справочном руководстве по API данных Google .

Вернуться наверх

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

Повторное получение ленты или записи

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

Для выполнения такого рода условного извлечения методы 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. Если ETags совпадают, то элемент не изменился, и сервер возвращает либо исключение HTTP 304 NotModifiedException .

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

Дополнительную информацию об ETags см. в справочном руководстве по API данных Google .

Вернуться наверх