Przewodnik po języku Java

Ważne: ten dokument został napisany przed 2012 rokiem. Opcje uwierzytelniania opisane w tym dokumencie (OAuth 1.0, AuthSub i ClientLogin) zostały oficjalnie wycofane 20 kwietnia 2012 r. i nie są już dostępne. Zachęcamy do jak najszybszego przejścia na OAuth 2.0.

Interfejs Google Sites Data API umożliwia aplikacjom klienckim uzyskiwanie dostępu do treści w Witrynie Google, ich publikowanie i modyfikowanie. Aplikacja kliencka może również prosić o listę ostatniej aktywności, pobrać historię zmian i pobrać załączniki.

Oprócz ogólnych informacji o możliwościach interfejsu Sites Data API ten przewodnik zawiera przykłady interakcji z interfejsem API za pomocą biblioteki klienta Java. Aby dowiedzieć się, jak skonfigurować bibliotekę klienta, przeczytaj artykuł Rozpoczynanie pracy z biblioteką klienta Google Data w języku Java. Jeśli chcesz dowiedzieć się więcej o podstawowym protokole używanym przez bibliotekę klienta Java do interakcji z interfejsem API klasycznych witryn, zapoznaj się z przewodnikiem po protokole.

Odbiorcy

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje klienckie współpracujące z Google Sites za pomocą biblioteki klienta Google Data w języku Java.

Pierwsze kroki

Witryny Google do uwierzytelniania używają kont Google lub kont G Suite. Jeśli masz już konto, nie musisz nic robić. W przeciwnym razie możesz utworzyć nowe konto.

Instalowanie biblioteki

Aby dowiedzieć się, jak skonfigurować i zainstalować bibliotekę klienta, przeczytaj artykuł Początkujący: korzystanie z biblioteki klienta Google Data w języku Java. Jeśli używasz Eclipse, w tym artykule znajdziesz też informacje o tym, jak skonfigurować projekt za pomocą wtyczki Eclipse do interfejsów Google Data API. Oto, co musisz zrobić:

  1. Zainstaluj Java w wersji 1.5 lub nowszej.
  2. Pobierz bibliotekę klienta (najnowszą wersję aplikacji gdata-src.java.zip).
  3. Pobierz listę zależnośći.
  4. Pobierz przykładowe aplikacje (najnowsza wersja gdata-samples.java.zip).

Po zainstalowaniu plików .jar musisz uwzględnić w projekcie te elementy:

  1. java/lib/gdata-sites-2.0.jar – wersja 2.0 jest przeznaczona do wersji 1.4 klasycznego interfejsu API witryn.
  2. java/lib/gdata-core-1.0.jar
  3. java/lib/gdata-client-1.0.jar
  4. java/lib/gdata-spreadsheet-3.0.jar (w przypadku pracy ze stronami lub elementami listy)

Pamiętaj też, aby dołączyć pliki JAR z zależnościami (gdata-media-1.0.jar, mail.jar i google-collect....jar).

Uruchamianie przykładowej aplikacji

Pełna, działająca aplikacja przykładowa znajduje się w podkatalogu /java/sample/sites w pliku gdata-samples.java.zip. Źródło jest też dostępne w folderze /trunk/java/sample/sites/ w repozytorium SVN, do którego można przejść z karty Źródło. SitesDemo.java umożliwia użytkownikowi wykonanie różnych operacji, które pokazują, jak korzystać z klasycznego interfejsu Sites API.

Uwaga: aby uruchomić próbkę, musisz dodać atrybut java/sample/util/lib/sample-util.jar.

Rozpoczynanie własnego projektu

Wskazówka: aby szybko skonfigurować interfejs Eclipse za pomocą naszego wtyczki Eclipse, przeczytaj artykuł Korzystanie z Eclipse w połączeniu z interfejsami Google Data API.

W zależności od potrzeb aplikacji musisz wykonać kilka importów. Zalecamy rozpoczęcie od tych importów:

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.*;

Następnie musisz też skonfigurować obiekt SitesService, który reprezentuje połączenie klienta z klasycznym interfejsem Sites API:

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

Argument applicationName powinien mieć format: company-applicationname-version. Ten parametr jest używany do rejestrowania.

Uwaga: w pozostałej części tego przewodnika przyjęto założenie, że w zmiennej client został utworzony SitesService.

Uwierzytelnianie w interfejsie API klasycznych Witryn

Biblioteki klienta Java można używać do pracy z publicznymi i prywatnymi kanałami danych. Interfejs Sites Data API zapewnia dostęp do prywatnych i publicznych kanałów danych w zależności od uprawnień do witryn i operacji, którą próbujesz wykonać. Możesz na przykład odczytać plik danych z treściami w publicznej witrynie, ale nie możesz go aktualizować – wymaga to uwierzytelnionego klienta. Można to zrobić za pomocą uwierzytelniania ClientLogin (nazwa użytkownika i hasło), AuthSub lub OAuth.

Więcej informacji o AuthSub, OAuth i ClientLogin znajdziesz w artykule Omówienie uwierzytelniania w interfejsach Google Data API.

Wskazówka: interfejs API obsługuje protokół SSL (HTTPS). Jeśli używasz AuthSub/OAuth, pamiętaj, aby określić zakres https://sites.google.com/feeds/, aby żądać plików danych przez SSL. Pamiętaj też, że w przypadku domen G Suite ustawienie „Wymagaj SSL” w administracyjnym panelu sterowania jest respektowane przez interfejs API. Możesz wymusić, aby wszystkie żądania interfejsu API były wysyłane przez HTTPS, wywołując funkcję client.useSsl();.

AuthSub w przypadku aplikacji internetowych

Uwierzytelnianie AuthSub w przypadku aplikacji internetowych powinno być używane przez aplikacje klienckie, które muszą uwierzytelniać użytkowników na kontach Google. Operator nie musi mieć dostępu do nazwy użytkownika i hasła użytkownika Google Sites – wymagany jest tylko token AuthSub.

Zobacz instrukcje włączania AuthSub w aplikacji internetowej

Prośba o token jednorazowego użytku

Gdy użytkownik po raz pierwszy otworzy Twoją aplikację, musi się uwierzytelnić. Zazwyczaj deweloperzy drukują tekst i link przekierowujący użytkownika na stronę zatwierdzania AuthSub w celu uwierzytelnienia użytkownika i prośby o dostęp do jego dokumentów. Biblioteka klienta w języku Java Data Google udostępnia funkcję do generowania tego adresu URL. Podany niżej kod łączy stronę AuthSubRequest.

import com.google.gdata.client.*;

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

Jeśli chcesz uwierzytelniać użytkowników w domenie hostowanej w G Suite:

import com.google.gdata.client.*;

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

Metoda getRequestUrl() bierze pod uwagę kilka parametrów (odpowiadających parametrom zapytania używanym przez moduł obsługi AuthSubRequest):

  • następny adres URL – adres URL, do którego Google przekieruje użytkownika po zalogowaniu się na konto i udzieleniu dostępu; http://www.example.com/welcome.jsp w przykładzie powyżej
  • scope – https://sites.google.com/feeds/ w przykładzie powyżej,
  • wartość logiczna wskazująca, czy token będzie używany w trybie rejestracji czy nie; false w przykładzie powyżej.
  • druga wartość logiczna wskazująca, czy token będzie później wymieniony na token sesji, czy nie; true w powyższym przykładzie.

Przejście na token sesji

Zobacz Używanie AuthSub z bibliotekami klienta interfejsu Google Data API.

Pobieranie informacji o tokenie sesji

Zobacz Korzystanie z AuthSub w bibliotekach klienta interfejsu Google Data API.

Unieważnianie tokena sesji

Zobacz Korzystanie z AuthSub w bibliotekach klienta interfejsu Google Data API.

OAuth w przypadku aplikacji internetowych lub zainstalowanych/mobilnych

Alternatywą dla protokołu AuthSub jest protokół OAuth. Jest on przeznaczony dla aplikacji internetowych. OAuth jest podobne do korzystania z trybu bezpiecznego i zarejestrowanego w AuthSub, ponieważ wszystkie żądania danych muszą być podpisane cyfrowo, a musisz zarejestrować swoją domenę.

Instrukcje włączania OAuth w zainstalowanej aplikacji

Pobieranie tokena żądania

Zobacz Używanie OAuth z bibliotekami klienta interfejsu Google Data API.

Autoryzacja tokena żądania

Zobacz Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.

Przejście na token dostępu

Zobacz Używanie OAuth z bibliotekami klienta interfejsu Google Data API.

ClientLogin w przypadku zainstalowanych aplikacji lub aplikacji mobilnych

ClientLogin powinien być używany przez zainstalowane aplikacje lub aplikacje mobilne, które muszą uwierzytelniać użytkowników na kontach Google. Podczas pierwszego uruchomienia aplikacja prosi użytkownika o podanie nazwy użytkownika i hasła. W kolejnych żądaniach odwołujesz się do tokenu uwierzytelniania.

Wyświetl instrukcje włączania ClientLogin do zainstalowanej aplikacji

Aby użyć ClientLogin, wywołaj metodę setUserCredentials() obiektu SitesService, który jest dziedziczony z GoogleService. Podaj adres e-mail i hasło użytkownika, w którego imieniu klient wysyła żądania. Na przykład:

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

Wskazówka: gdy aplikacja po raz pierwszy uwierzytelni użytkownika, zapisz token uwierzytelniający w bazie danych, aby można go było później odtworzyć. Nie musisz prosić użytkownika o hasło przy każdym uruchomieniu aplikacji. Więcej informacji znajdziesz w artykule na temat wycofywania tokena uwierzytelniania.

Więcej informacji o używaniu funkcji ClientLogin w aplikacjach w języku Java znajdziesz w artykule Korzystanie z funkcji ClientLogin w bibliotekach klienta interfejsu Google Data API.

Powrót do góry

Plik danych witryny

Plik danych o witrynach może zawierać listę witryn Google Sites, których użytkownik jest właścicielem lub do których ma uprawnienia do wyświetlania. Możesz też użyć tej opcji, aby zmienić nazwę istniejącej witryny. W przypadku domen G Suite możesz też użyć tej funkcji do tworzenia lub kopiowania całej witryny.

Strony z ofertami

Aby wysłać zapytanie do pliku danych witryny, wyślij żądanie HTTP GET do adresu URL pliku danych witryny:

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

W kliencie Java możesz używać klas SiteFeed i SiteEntry do obsługi pliku danych o witrynach:

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("");
  }
}

Powyższy fragment zawiera tytuł i nazwę witryny oraz jej motyw. Dostępna jest też inna funkcja gettera służąca do uzyskiwania dodatkowych właściwości w pliku danych.

Tworzenie nowych witryn

Uwaga: ta funkcja jest dostępna tylko w domenach G Suite.

Możesz udostępnić nowe witryny, tworząc nowy obiekt SiteEntry i wywołując metodę insert() klienta w pliku danych witryny.

W tym przykładzie tworzymy zupełnie nową witrynę z tematem „Slate” (ustawienie opcjonalne) oraz podajemy jej nazwę (wymaganą) i opis (opcjonalny):

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

Powyższe żądanie spowoduje utworzenie nowej witryny w domenie G Suite example.com. Adres URL witryny będzie więc wyglądać tak: https://sites.google.com/a/example.com/tytuł-mojej-witryny.

Jeśli witryna zostanie utworzona, serwer odpowie obiektem SiteEntry, wypełnionym elementami dodanymi przez serwer: linkiem do witryny, linkiem do pliku ACL witryny, nazwą witryny, tytułem, podsumowaniem itp.

Kopiowanie witryny

Uwaga: ta funkcja jest dostępna tylko w domenach G Suite.

Kopiowanie witryny jest podobne do tworzenia nowej witryny. Różnica polega na tym, że na nowym SiteEntry musisz ustawić link prowadzący do witryny, który będzie duplikatem. Oto przykład duplikowania witryny utworzonej w sekcji Tworzenie nowych witryn:

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

Ważne informacje:

  • Kopiowane mogą być tylko witryny i szablony witryn należące do uwierzytelnionego użytkownika.
  • Możesz też skopiować szablon witryny. Witryna jest szablonem, jeśli na stronie ustawień Google Sites zaznaczona jest opcja „Opublikuj tę witrynę jako szablon”.
  • Możesz skopiować witrynę z innej domeny, o ile jesteś właścicielem witryny źródłowej.

Aktualizowanie metadanych witryny

Aby zmienić nazwę witryny albo zmienić jej motyw, tag kategorii lub podsumowanie, musisz najpierw pobrać plik SiteEntry zawierający daną witrynę, zmodyfikować co najmniej jedną właściwość, a potem wywołać metodę update() SiteEntry. W tym przykładzie modyfikujemy motyw poprzedniej witryny i zmieniamy jej nazwę:

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

Mapowania adresów internetowych

Mapowania adresów internetowych umożliwiają użytkownikom Witryn zmapowanie własnych domen na witrynę Google. Na przykład http://www.mydomainsite.com można użyć zamiast http://sites.google.com/a/domain.com/mysite. W zależności od tego, gdzie jest hostowana Twoja witryna, możesz ręcznie zmodyfikować mapowania adresów internetowych witryny. Więcej informacji znajdziesz w tym artykule w Centrum pomocy.

Pobieranie mapowań adresów internetowych witryny

Aby pobrać mapowania adresów internetowych witryny, pobierz wpis/plik danych witryny z parametrem 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());
  }
}

Istniejące mapowania będą wyświetlane jako link z atrybutem rel=„webAddressMapping”. Na przykład w powyższym przykładzie są 3 elementy webAddressMapping, które wskazują na stronę http://sites.google.com/site/myOtherTestSite.

Modyfikowanie mapowań adresów internetowych

Uwaga: podczas mapowania adresów internetowych wszystkie operacje GET/POST/PUT powinny mieć określony parametr with-mappings=true. Jeśli tego parametru nie ma, elementy webAddressMapping nie będą zwracane we wpisach witryny (GET) ani uwzględniane podczas aktualizowania/usuwania mapowań (PUT) z wpisu.

Aby dodać, zaktualizować lub usunąć mapowanie, po prostu podaj, zmień lub usuń taki link podczas tworzenia nowych witryn lub aktualizowania metadanych witryny. W identyfikatorze URI kanału witryny należy umieścić parametr with-mappings=true. Uwaga: aby zaktualizować mapowanie adresów, musisz być administratorem witryny lub administratora domeny w przypadku witryny hostowanej w G Suite.

Na przykład żądanie poniżej aktualizuje mapowanie http://www.mysitemapping.com na http://www.my-new-sitemapping.com i usuwa http://www.mysitemapping2.com, pozostawiając link poza wpisem:

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

Pamiętaj, że mapowania adresu internetowego można też określić podczas tworzenia lub kopiowania witryny.

Powrót do góry

Obszar aktywności

Możesz pobrać ostatnią aktywność (zmiany) na stronie, pobierając kanał aktywności. Każdy wpis w strumieniach aktywności zawiera informacje o zmianie wprowadzonej w witrynie.

Aby wysłać zapytanie dotyczące kanału aktywności, wyślij żądanie HTTP GET na adres URL kanału aktywności:

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

W kliencie Java użyj klasy ActivityFeed, aby zwrócić obiekty 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());
  }
}

Uwaga: aby mieć dostęp do tego pliku danych, musisz być współpracownikiem lub właścicielem witryny. Klient musi się uwierzytelnić za pomocą tokena AuthSub, OAuth lub ClientLogin. Zobacz artykuł Uwierzytelnianie w usłudze Witryny.

Powrót do góry

Kanał wersji

Aby pobrać historię zmian dowolnego wpisu w treści, wyślij żądanie HTTP GET na link do wersji wpisu:

https://sites.google.com/feeds/revision/site/siteName/CONTENT_ENTRY_ID

W tym przykładzie najpierw wysyłamy zapytanie do kanału treści, a potem pobieramy kanał zmian dla pierwszego wpisu treści:

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

Uwaga: aby uzyskać dostęp do tego pliku danych, musisz być współpracownikiem lub właścicielem witryny. Klient musi się uwierzytelnić za pomocą tokena AuthSub, OAuth lub ClientLogin. Zobacz artykuł Uwierzytelnianie w usłudze Witryny.

Powrót do góry

Źródło treści

Pobieram źródło treści

Kanał treści zawiera najnowsze treści z witryny. Dostęp do niego można uzyskać, wysyłając żądanie HTTP GET na adres URL źródła treści:

https://sites.google.com/feeds/content/site/siteName
Parametr pliku danychOpis
site„site” lub domenę hostowaną w G Suite (np. example.com).
siteNameNazwa przestrzeni internetowej Twojej witryny podana w jej adresie URL (np. mySite).

Przykład pobierania źródła treści:

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

Wynik contentFeed to obiekt ContentFeed zawierający odpowiedź serwera. Każdy wpis w sekcji contentFeed reprezentuje inną stronę lub inny element w witrynie użytkownika. Obiekt ContentFeed będzie zawierać różne typy obiektów, które są dziedziczone z obiektu BaseContentEntry: ListItemEntry, ListPageEntry, AttachmentEntry, WebAttachmentEntry, FileCabinetPageEntry, AnnouncementsPageEntry, AnnouncementEntry, WebPageEntry, CommentEntry.

Oto przykład listy różnych typów wpisów w pliku ContentFeed. Każdy typ wpisu ma inne właściwości, ale nie wszystkie są tu wydrukowane.

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

Uwaga: ten plik danych może wymagać uwierzytelnienia lub nie, w zależności od uprawnień do udostępniania na stronie. Jeśli witryna jest prywatna, klient musi się uwierzytelnić za pomocą tokena AuthSub, OAuth lub ClientLogin. Zobacz artykuł Uwierzytelnianie w usłudze Witryny.

Przykłady zapytań dotyczących źródła treści

Plik danych z treścią możesz przeszukiwać, korzystając z niektórych standardowych parametrów zapytania w interfejsie Google Data API oraz parametrów dotyczących interfejsu API klasycznej wersji Witryn. Więcej szczegółowych informacji oraz pełną listę obsługiwanych parametrów znajdziesz w przewodniku po dokumentach referencyjnych.

Uwaga: w przykładach w tej sekcji używana jest metoda buildContentFeedUrl() z sekcji Pobieranie pliku danych.

Pobieranie określonych rodzajów wpisów

Aby pobrać tylko określony typ wpisu, użyj parametru kind. Ten przykład zwraca tylko rekordy 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());
}

Aby zwrócić więcej niż 1 typ wpisu, oddziel każdy kind przecinkiem. W tym przykładzie zwracane są wpisy filecabinet i 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());
}

Pobieranie strony według ścieżki

Jeśli znasz ścieżkę względną strony w Google Site, możesz użyć parametru path, aby pobrać tę stronę. W tym przykładzie zwrócona zostanie strona o adresie 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());
}

Pobieranie wszystkich wpisów na stronie nadrzędnej

Jeśli znasz identyfikator wpisu treści strony (np. „1234567890” w przykładzie poniżej), możesz użyć parametru parent, aby pobrać wszystkie podrzędne wpisy (jeśli istnieją):

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

Dodatkowe parametry znajdziesz w Przewodniku.

Powrót do góry


Tworzenie treści

Uwaga: zanim utworzysz treści dla witryny, upewnij się, że masz ją skonfigurowaną w kliencie.
client.site = "siteName";

Nowe treści (strony internetowe, strony z listami, strony katalogu plików, strony z ogłoszeniami itp.) można utworzyć, wysyłając HTTP POSTdo pliku danych treści:

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

Listę obsługiwanych typów węzłów znajdziesz w parametry kind w przewodniku po funkcji.

Tworzenie nowych elementów lub stron

W tym przykładzie tworzymy nowy element webpage na najwyższym poziomie witryny, dodajemy do niego trochę kodu XHTML, który będzie stanowił treść strony, a następnie ustawiamy tytuł nagłówka na „Nowy tytuł strony internetowej”:

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

Jeśli żądanie zostanie spełnione, element createdEntry będzie zawierać kopię utworzonego na serwerze wpisu.

Tworzenie elementów/stron za pomocą niestandardowych ścieżek adresów URL

W przypadku poprzedniego przykładu strona zostanie utworzona pod adresem URL http://sites.google.com/site/siteName/new-webpage-title i będzie mieć nagłówek „Nowy tytuł strony internetowej”. Oznacza to, że <atom:title> jest normalizowane do new-webpage-title w przypadku adresu URL. Aby dostosować ścieżkę adresu URL strony, możesz ustawić element <sites:pageName>.

W tym przykładzie tworzymy nową stronę filecabinet z nagłówkiem „Miejsce na pliki”, ale stronę z adresem URL http://sites.google.com/site/siteName/files (zamiast http://sites.google.com/site/siteName/file-storage) tworzymy przez określenie elementu <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());

Serwer używa następujących reguł pierwszeństwa przy nazywaniu ścieżki adresu URL strony:

  1. <sites:pageName>, jeśli występuje. Wymagana jest wartość w polu a-z, A-Z, 0-9, -, _.
  2. <atom:title> nie może być puste, jeśli parametr pageName jest nieobecny. Normalizacja polega na przycięciu i skróceniu spacji do „-” oraz usunięciu znaków, które nie pasują do a-z, A-Z, 0-9, -, _.

Tworzenie podstron

Aby utworzyć podstrony (strony podrzędne) w ramach strony nadrzędnej, musisz we wpisie ustawić link nadrzędny. Atrybut href linku do linku do siebie w węźle nadrzędnym.

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

W powyższym przykładzie tworzymy nowy element announcement na pierwszej stronie z powiadomieniami w źródle treści użytkownika. Tytuł ogłoszenia to „Impreza!”, a treść to „Moje mieszkanie, w ten weekend”.

Szablony stron

Tworzenie szablonów stron

Proces tworzenia szablonu strony jest taki sam jak w przypadku tworzenia nowych elementów/stron i tworzenia podstron. Różnica polega na dodaniu elementu category z terminem i etykietą odpowiednio „http://schemas.google.com/g/2005#template” i „template”.

W tym przykładzie tworzymy nowy szablon 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);

Tworzenie stron na podstawie szablonu

Podobnie jak w przypadku szablonów stron, możesz utworzyć nową stronę na podstawie szablonu, dodając element <link> z wartością rel='http://schemas.google.com/sites/2008#template' wskazujący na link do szablonu strony.

W tym przykładzie tworzymy nowy szablon filecabinet, a następnie na jego podstawie tworzy nową stronę 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);

Uwaga: pomimo szablonu definiującego element <category>, który znajduje się w Twoim wpisie, nadal jest on wymagany. Pamiętaj też, że jeśli dodasz element <content>, serwer go odrzuci.

Przesyłanie plików

Podobnie jak w przypadku Witryn Google, interfejs API obsługuje przesyłanie załączników na stronie magazynu plików lub na stronie nadrzędnej.

Aby przesłać załącznik do elementu nadrzędnego, wyślij żądanie HTTP POST na adres URL pliku danych:

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

Wszystkie typy załączników muszą być przesłane na stronę nadrzędną. Dlatego musisz ustawić link nadrzędny w obiekcie AttachmentEntry lub WebAttachmentEntry, który chcesz przesłać. Więcej informacji znajdziesz w artykule Tworzenie stron podrzędnych.

Przesyłam załączniki

W tym przykładzie plik PDF jest przesyłany do pierwszego FileCabinetPageEntry znalezionego w strumieniach treści użytkownika. Załącznik zostanie utworzony z tytułem „Pierwsze kroki” i (opcjonalnie) opisem „Pakiet 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!");

Jeśli przesyłanie się uda, attachment będzie zawierać kopię utworzonego załącznika.

Przesyłanie załącznika do folderu

Aby przesłać załącznik do istniejącego folderu w folderze FileCabinetPageEntry, dodaj kategorię z atrybutem „term” ustawionym na nazwę folderu. Na przykład dodaj ten wiersz w pliku uploadAttachment():

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

Załączniki internetowe

Załączniki internetowe to specjalne rodzaje załączników. To linki do innych plików w internecie, które możesz dodać do listy plików w folderze. Ta funkcja jest analogiczna do metody przesyłania „Dodaj plik za pomocą adresu URL” w interfejsie Witryn Google.

Uwaga: załączniki internetowe można tworzyć tylko w sekcji szafy. Nie można ich przesyłać na inne typy stron.

W tym przykładzie tworzymy WebAttachmentEntry w ramach pierwszego FileCabinetPageEntry znalezionego w strumieniach treści użytkownika. Jego tytuł i (opcjonalnie) opis mają odpowiednio wartości „GoogleLogo” i „ładne kolory”.

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 tworzy w skrzynce użytkownika link do obrazu o adresie „http://www.google.com/images/logo.gif”.

Powrót do góry


Aktualizowanie treści

Aktualizowanie metadanych lub zawartości HTML strony

Metadane (tytuł, pageName itp.) i treść strony dowolnego typu BaseContentEntry można edytować za pomocą metody update() wpisu. Spowoduje to wysłanie żądania HTTP PUT do linku editz danymi.

Poniżej znajdziesz przykład aktualizacji elementu ListPageEntry z tymi zmianami:

  • Tytuł został zmieniony na „Zaktualizowany tytuł”.
  • Zawartość HTML strony jest aktualizowana do <p>Zaktualizowana zawartość HTML</p>.
  • Nagłówek pierwszej kolumny listy został zmieniony na „Właściciel”.
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!");

Aktualizowanie zawartości pliku załącznika

W przypadku AttachmentEntry możesz też zaktualizować treść, ustawiając wartość MediaSource wpisu, a następnie używając metody updateMedia(boolean) wpisu.

W tym przykładzie zaktualizujemy zawartość istniejącego załącznika:

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

Przykładowy kod wysyła żądanie HTTP PUT do linku edit-media wpisu. Zwrócony obiekt AttachmentEntry będzie zawierać zaktualizowane treści.

Aktualizowanie metadanych i treści załącznika

Możesz zaktualizować metadane załącznika i jego zawartość w tym samym wywołaniu, używając metody updateMedia(). Czy możesz zaktualizować tylko zawartość pliku, metadane lub jedno i drugie.

W tym przykładzie zmieniamy tytuł załącznika na „Nowy tytuł”, aktualizujemy jego opis i zastępujemy zawartość pliku nowym plikiem ZIP. Żądanie zawiera nową zawartość pliku, więc używany jest identyfikator updateMedia() obiektu 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");

Powrót do góry


Usuwanie treści

Aby usunąć stronę lub element z witryny Google, najpierw pobierz wpis treści, a następnie wywołaj dla niego delete().

entry.delete();

Możesz też użyć metody delete() klasy usługi, przekazując jej link edit i wartość ETag:

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

Jeśli wpis został usunięty, serwer odpowie kodem HTTP 200 OK.

Powrót do góry


Pobieranie załączników

Aby pobrać AttachmentEntry, wyślij żądanie HTTP GET do linku do treści źródłowej wpisu.

W tym przykładzie pobierany jest pierwszy element AttachmentEntry znaleziony w pliku danych użytkownika do katalogu „/ścieżka/do/pliku/do/zapisu”:

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

Powrót do góry

Kanał ACL

Omówienie uprawnień do udostępniania (ACL)

Każdy wpis ACL w pliku danych ACL reprezentuje rolę dostępu określonego elementu, np. użytkownika, grupy użytkowników, domeny lub domyślnego dostępu (czyli witryny publicznej). Wpisy będą wyświetlane tylko w przypadku podmiotów z wyraźnym dostępem. Na panelu „Osoby z dostępem” w ekranie udostępniania w interfejsie Google Sites będzie widoczny po jednym wpisie dla każdego adresu e-mail. W rezultacie administratorzy domen nie będą widoczni, mimo że mają domyślny dostęp do witryny.

Role

Element roli reprezentuje poziom dostępu, jaki może mieć encja. Element gAcl:role może mieć 4 wartości:

  • Odczytujący – wyświetlający (odpowiednik dostępu tylko do odczytu).
  • writer (pisarz) – współpracownik (odpowiednik uprawnień do odczytu i zapisu).
  • owner – zwykle jest administratorem witryny (odpowiednik uprawnień do odczytu i zapisu).

Zakresy

Element zakresu reprezentuje element, który ma ten poziom dostępu. Element gAcl:scope może zawierać 4 rodzaje:

  • użytkownik – wartość adresu e-mail, np. „użytkownik@gmail.com”.
  • group – adres e-mail Grupy dyskusyjnej Google, np. „group@domain.com”.
  • domena – nazwa domeny G Suite, np. „domena.com”.
  • domyślny – istnieje tylko jeden możliwy zakres typu „domyślny”, który nie ma wartości (np. <gAcl:scope type="default">). Ten konkretny zakres kontroluje dostęp, który każdy użytkownik ma domyślnie w witrynie publicznej.

Uwaga: domeny nie mogą mieć wartości gAcl:role ustawionej na poziomie dostępu „właściciel”. Mogą to być tylko czytelnicy lub zapisy.

Pobieranie pliku danych ACL

Klasy AclFeed i AclEntry mogą służyć do kontrolowania uprawnień do udostępniania witryny i można je pobrać za pomocą metody getFeed() klasy usługi.

W tym przykładzie pobieramy kanał ACL dla danej witryny i wypisujemy uprawnienia dla każdego 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');

Jeśli pracujesz z rekordami w pliku SiteFeed, każdy element SiteEntry zawiera link do pliku danych ACL. Na przykład ten fragment kodu pobiera plik danych listy kontroli dostępu (ACL) identyfikatora SiteEntry:

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

Udostępnianie witryny

Uwaga: udostępnianie niektórych list kontroli dostępu może być możliwe tylko wtedy, gdy konfiguracja domeny zezwala na takie uprawnienia (np.udostępnianie poza domenę w przypadku domen G Suite jest włączone itp.).

Aby udostępnić witrynę Google za pomocą interfejsu API, klient musi utworzyć nowy obiekt AclEntry i POST go na serwerze.

Oto przykład dodawania użytkownika „użytkownik@domena.com” jako reader w witrynie:

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

Możliwe wartości AclScope i AclRoles znajdziesz w sekcji Przegląd pliku danych ACL.

Udostępnianie na poziomie grupy i domeny

Podobnie jak w przypadku udostępniania witryny jednemu użytkownikowi możesz udostępnić ją całej grupie dyskusyjnej Google lub domenie G Suite.

Udostępnianie przy użyciu adresu e-mail grupy:

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

Udostępnianie całej domenie:

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

Udostępnianie na poziomie domeny jest obsługiwane tylko w przypadku domen G Suite i tylko w przypadku domeny, w której hostowana jest witryna. Na przykład witryna http://sites.google.com/a/domain1.com/siteA może udostępniać całą witrynę tylko użytkownikom z domeny domain1.com, a nie z domeny domain2.com. Witryny, które nie są hostowane w domenie G Suite (np. http://sites.google.com/site/siteB), nie mogą zapraszać domen.

Modyfikowanie uprawnień do udostępniania

Aby zmienić istniejące uprawnienia do udostępniania w witrynie, najpierw pobierz obiekt AclEntry, zmień uprawnienia zgodnie z potrzebami, a potem wywołaj metodę update() obiektu AclEntry, aby zmodyfikować listę ACL na serwerze.

W tym przykładzie modyfikujemy poprzedni przykład aclEntry z sekcji Udostępnianie witryny, zmieniając użytkownika „użytkownik@example.com” na użytkownika writer (współpracownika): 

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

Więcej informacji o tagach ETag znajdziesz w przewodniku po interfejsach API danych Google.

Usuwanie uprawnień do udostępniania

Aby usunąć uprawnienia do udostępniania, najpierw pobierz obiekt AclEntry, a następnie wywołaj jego metodę delete():

aclEntry.delete();

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

Więcej informacji o eTag znajdziesz w przewodniku po interfejsach Google Data API.

Powrót do góry

Tematy specjalne

Ponowne pobieranie pliku danych lub wpisu

Jeśli chcesz pobrać wcześniej pobrany plik lub wpis, możesz zwiększyć wydajność, prosząc serwer o wysłanie listy lub wpisu tylko wtedy, gdy zmieniły się one od czasu ostatniego pobrania.

Aby umożliwić takie wyszukiwanie warunkowe, metody getFeed() i getEntry() zawierają dodatkowy argument, który akceptuje wartość ETag lub obiekt DateTime dla nagłówka If-Modified-Since. Etag wpisu możesz uzyskać z poziomu entry.getEtag().

W tym przykładzie wykonywane jest warunkowe pobieranie pozycji strony z treścią:

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

Po otrzymaniu tego żądania serwer sprawdza, czy żądany element ma ten sam tag ETag co określony przez Ciebie. Jeśli tagi ETagi są zgodne, oznacza to, że element się nie zmienił, a serwer zwróci wyjątek HTTP 304 NotModifiedException.

Jeśli znaczniki ETag się nie zgadzają, oznacza to, że element został zmodyfikowany od ostatniego żądania i serwer zwraca ten element.

Więcej informacji o eTag znajdziesz w przewodniku po interfejsach Google Data API.

Powrót do góry