Ważne: ten dokument został stworzony przed 2012 rokiem. Opcje uwierzytelniania opisane w tym dokumencie (protokół 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 protokół OAuth 2.0.
Interfejs API danych Witryn Google umożliwia aplikacjom klienckim dostęp do Witryn Google oraz ich publikowanie i modyfikowanie. Aplikacja kliencka może również prosić o listę ostatnich działań, historię zmian i załączniki.
Oprócz ogólnych informacji o możliwościach interfejsu Sites Data API, w tym przewodniku znajdziesz przykłady interakcji z interfejsem API za pomocą biblioteki klienta w języku Java. Informacje o konfigurowaniu biblioteki klienta znajdziesz w artykule o pierwszych krokach z biblioteką klienta Google Data Java. Jeśli chcesz dowiedzieć się więcej o protokole używanym przez bibliotekę kliencką w języku Java do interakcji z klasycznym interfejsem Sites API, zapoznaj się z przewodnikiem po protokołach.
Odbiorcy
Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje klienckie, które współdziałają z Witrynami Google przy użyciu biblioteki klienta na temat danych Google w języku Java.
Pierwsze kroki
Witryny Google używają do uwierzytelniania kont Google lub kont G Suite. Jeśli masz już konto, nie musisz nic więcej robić. W przeciwnym razie możesz utworzyć nowe konto.
Instalowanie biblioteki
Aby uzyskać pomoc przy konfigurowaniu i instalowaniu biblioteki klienta, zobacz Wprowadzenie do biblioteki klienta Google Data Java. Jeśli używasz Eclipse, z tego artykułu dowiesz się też, jak skonfigurować projekt za pomocą wtyczki Eclipse do interfejsów API danych Google. Aby rozpocząć, wykonaj te czynności:
- Zainstaluj Javę w wersji 1.5 lub nowszej
- Pobierz bibliotekę klienta (najnowszą wersję
gdata-src.java.zip
). - Pobierz listę zależności
- Pobierz przykładowe aplikacje (najnowszą wersję aplikacji
gdata-samples.java.zip
)
Po zainstalowaniu pliku .jar musisz dodać do projektu następujące elementy:
java/lib/gdata-sites-2.0.jar
– wersja 2.0 jest przeznaczona do wersji 1.4 klasycznej wersji interfejsu API Witryn.java/lib/gdata-core-1.0.jar
java/lib/gdata-client-1.0.jar
java/lib/gdata-spreadsheet-3.0.jar
(w przypadku pracy ze stronami i elementami listy)
Pamiętaj też, aby dodać pliki jar zależności (gdata-media-1.0.jar
, mail.jar
i google-collect....jar
).
Uruchamianie przykładowej aplikacji
Pełna działająca przykładowa aplikacja znajduje się w podkatalogu /java/sample/sites
w pliku gdata-samples.java.zip
do pobrania.
Źródło jest też dostępne na stronie /trunk/java/sample/sites/ w repozytorium SVN dostępnym na karcie Źródło. SitesDemo.java
pozwala użytkownikowi wykonać wiele operacji, które pokazują, jak używać klasycznego interfejsu API Witryn.
Pamiętaj, że musisz dodać java/sample/util/lib/sample-util.jar
, aby uruchomić próbkę.
Rozpoczynanie własnego projektu
Wskazówka: aby szybko skonfigurować naszą wtyczkę Eclipse, przeczytaj artykuł Korzystanie z Eclipse z interfejsami API danych Google.
W zależności od potrzeb aplikacji można przeprowadzić kilka importów. Zalecamy rozpocząć 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 służy do logowania.
Uwaga: w pozostałej części tego przewodnika przyjęto założenie, że w zmiennej client
masz utworzoną SitesService
.
Uwierzytelnianie w klasycznej wersji interfejsu API Witryn
Biblioteki klienta w Javie można używać do pracy z publicznymi lub prywatnymi kanałami. Interfejs Sites Data API zapewnia dostęp do prywatnych i publicznych kanałów w zależności od uprawnień Witryn i operacji, którą chcesz wykonać. Możesz na przykład odczytywać kanał treści witryny publicznej, ale nie wprowadzać w niej aktualizacji – coś, co wymaga uwierzytelnionego klienta. Możesz to zrobić za pomocą uwierzytelniania za pomocą nazwy użytkownika/hasła ClientLogin, AuthSub lub OAuth.
Zapoznaj się z omówieniem uwierzytelniania interfejsów API danych Google, aby dowiedzieć się więcej o AuthSub, OAuth i ClientLogin.
Wskazówka: interfejs API obsługuje protokół SSL (HTTPS). Jeśli korzystasz z protokołu AuthSub/OAuth, określ zakres https://sites.google.com/feeds/
, aby móc żądać kanałów 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ć stosowanie protokołu HTTPS przez wszystkie żądania do interfejsu API, wywołując metodę client.useSsl();
.
AuthSub dla aplikacji internetowych
Z uwierzytelniania AuthSub w aplikacjach internetowych powinny korzystać aplikacje klienckie, które muszą uwierzytelniać użytkowników na kontach Google. Operator nie wymaga dostępu do nazwy użytkownika i hasła użytkownika Witryn Google – wymagany jest tylko token AuthSub.
Wyświetl instrukcje włączania AuthSub do aplikacji internetowej
Poproś o token jednorazowy
Gdy użytkownik po raz pierwszy korzysta z Twojej aplikacji, musi się uwierzytelnić. Zwykle deweloperzy drukują tekst i link przekierowujący użytkownika na stronę zatwierdzania AuthSub, aby uwierzytelnić użytkownika i poprosić o dostęp do dokumentów. Biblioteka klienta Google Data Java udostępnia funkcję generowania tego adresu URL. Poniższy kod tworzy link do strony 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 swojej domenie hostowanej 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()
przyjmuje kilka parametrów (odpowiadających parametrom zapytania używanym przez moduł obsługi AuthSubRequest):
- next URL (następny adres URL) – adres URL, na który Google przekieruje użytkownika po zalogowaniu się na konto i przyznaniu dostępu;
http://www.example.com/welcome.jsp
w przykładzie powyżej. - zakres –
https://sites.google.com/feeds/
w powyższym przykładzie; - wartość logiczna wskazująca, czy token będzie używany w trybie rejestracji; w tym przypadku
false
- druga wartość logiczna wskazująca, czy token będzie później wymieniany na token sesji (
true
w powyższym przykładzie).
Przechodzenie na token sesji
Zobacz Używanie AuthSub z bibliotekami klienta interfejsu Google Data API.
Pobieranie informacji o tokenie sesji
Zobacz Używanie AuthSub z bibliotekami klienta interfejsu Google Data API.
Unieważnianie tokena sesji
Zobacz Używanie AuthSub z bibliotekami klienta interfejsu Google Data API.
OAuth w przypadku aplikacji internetowych lub zainstalowanych/mobilnych
Protokół OAuth może być używany jako alternatywa dla protokołu AuthSub i jest przeznaczony dla aplikacji internetowych. Protokół OAuth przypomina korzystanie z trybu bezpiecznego i zarejestrowanego AuthSub, ponieważ wszystkie żądania danych muszą być podpisane cyfrowo i trzeba zarejestrować swoją domenę.
Wyświetl instrukcje wdrażania protokołu OAuth w zainstalowanej aplikacji
Pobieram token żądania
Przeczytaj artykuł Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.
Autoryzacja tokena żądania
Przeczytaj artykuł Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.
Przejście na token dostępu
Przeczytaj artykuł Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.
ClientLogin dla aplikacji zainstalowanych/mobilnych
ClientLogin powinien być używany przez zainstalowane lub mobilne aplikacje, które muszą uwierzytelniać użytkowników na kontach Google. Przy pierwszym uruchomieniu aplikacja prosi o podanie nazwy użytkownika i hasła. W kolejnych żądaniach odwołuje się do tokena uwierzytelniania.
Wyświetl instrukcje włączania ClientLogin do zainstalowanej aplikacji
Aby użyć ClientLogin, wywołaj metodę setUserCredentials()
obiektu SitesService
, która jest dziedziczona z elementu GoogleService
. Podaj adres e-mail i hasło użytkownika, w imieniu którego Twój 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 uwierzytelniania w bazie danych, aby móc go przywrócić do późniejszego użycia. Nie trzeba prosić użytkownika o podanie hasła przy każdym uruchomieniu aplikacji. Więcej informacji znajdziesz w artykule Wycofywanie tokena uwierzytelniania.
Więcej informacji o korzystaniu z ClientLogin w aplikacjach w Javie znajdziesz w artykule Korzystanie z ClientLogin w połączeniu z bibliotekami klienta interfejsu Google Data API.
Kanał witryny
Kanał witryny może służyć do wyświetlania listy Witryn Google, które należą do użytkownika lub do których ma uprawnienia do wyświetlania. Za jego pomocą można również zmienić nazwę istniejącej witryny. W przypadku domen G Suite można też używać tej funkcji do tworzenia lub kopiowania całej witryny.
Wyświetlanie listy witryn
Aby przesłać zapytanie do kanału witryny, wyślij żądanie HTTP GET
pod adres URL tego kanału:
https://sites.google.com/feeds/site/site/
W kliencie Java do pracy z plikiem danych witryny możesz używać klas SiteFeed
i 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(""); } }
Powyższy fragment zawiera tytuł witryny, nazwę witryny i jej motyw. Inne metody pobierania pozwalają uzyskać dostęp do dodatkowych właściwości w pliku danych.
Tworzenie nowych witryn
Uwaga: ta funkcja jest dostępna tylko w domenach G Suite.
Aby udostępnić nowe witryny, utwórz nowy element SiteEntry
i wywołaj metodę insert()
klienta w pliku danych witryny.
W tym przykładzie tworzona jest nowa witryna z motywem „Plansza” (ustawienie opcjonalne) oraz jej nazwą (wymaganą) i opisem (opcjonalnie):
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 w odpowiedzi zwróci obiekt SiteEntry
zawierający elementy dodane przez serwer: link do witryny, link do kanału ACL witryny, nazwę witryny, tytuł, podsumowanie itd.
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 w nowym SiteEntry
musisz ustawić link zawierający własny link do witryny, który chcesz zduplikować.
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 uwagi:
- Można kopiować tylko witryny i szablony witryn należące do uwierzytelnionego użytkownika.
- Szablon witryny można też skopiować. Witryna jest szablonem, jeśli na stronie ustawień Witryn Google zaznaczone jest ustawienie „Opublikuj tę witrynę jako szablon”.
- Możesz skopiować witrynę z innej domeny – jeśli nie jesteś właścicielem witryny źródłowej.
Aktualizowanie metadanych witryny
Aby zmienić nazwę witryny, zmienić jej motyw, tag kategorii lub podsumowanie, musisz najpierw pobrać plik SiteEntry
zawierający odpowiednią witrynę, zmodyfikować co najmniej jedną właściwość, a potem wywołać metodę update()
metody SiteEntry
.
Ten przykład modyfikuje motyw poprzedniej witryny i zmienia nazwę witryny:
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
Mapowanie adresów internetowych umożliwia użytkownikom Witryn Google mapowanie własnych domen na witryny w Witrynach Google. Na przykład zamiast http://sites.google.com/a/domain.com/mysite
można użyć http://www.mydomainsite.com
. W zależności od tego, gdzie znajduje się Twoja witryna, możesz ręcznie zmienić mapowanie jej adresów internetowych. Więcej informacji znajdziesz w artykule w Centrum pomocy.
Pobieranie mapowania adresu internetowego witryny
Aby zwrócić mapowanie adresu internetowego witryny, pobierz wpis/kanał 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'. W powyższym przykładzie widać 3 elementy webAddressMapping
prowadzące do witryny http://sites.google.com/site/myOtherTestSite
.
Modyfikowanie mapowań adresów internetowych
Uwaga: podczas pracy z mapowaniem adresów internetowych wszystkie operacje GET/POST/PUT powinny określać parametr with-mappings=true
. Jeśli ten parametr nie jest określony, parametry 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, wystarczy określić, zmienić lub usunąć taki link podczas tworzenia nowych witryn lub aktualizowania metadanych witryny. W identyfikatorze URI pliku danych witryny należy podać parametr with-mappings=true
.
Uwaga: aby zaktualizować mapowania adresów, musisz być administratorem witryny lub domeny w przypadku witryny hostowanej w G Suite.
Na przykład poniższe żądanie aktualizuje mapowanie http://www.mysitemapping.com
na http://www.my-new-sitemapping.com
oraz usuwa http://www.mysitemapping2.com
, pozostawiając link we wpisie:
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();
Uwaga: mapowanie adresów internetowych można też określić podczas tworzenia lub kopiowania witryny.
Lista aktywności
Możesz pobrać ostatnią aktywność w witrynie (zmiany), pobierając kanał aktywności. Każdy wpis w źródle aktywności zawiera informacje o zmianie w witrynie.
Aby przesłać zapytanie do kanału aktywności, wyślij żądanie HTTP GET
na jego adres URL:
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 uzyskać dostęp do tego kanału, musisz być współpracownikiem lub właścicielem witryny. Twój klient musi uwierzytelnić się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.
Plik danych wersji
Aby pobrać historię zmian dowolnego wpisu treści, wyślij HTTP GET
do linku do wersji wpisu:
https://sites.google.com/feeds/revision/site/siteName/CONTENT_ENTRY_ID
Ten przykład wysyła zapytanie do kanału treści, a następnie pobiera kanał wersji 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 mieć dostęp do tego kanału, musisz być współpracownikiem lub właścicielem witryny. Twój klient musi uwierzytelnić się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.
Źródło treści
Pobieranie źródła treści
Źródło treści zawiera listę najnowszych treści w witrynie. Aby uzyskać do niego dostęp, wyślij żądanie HTTP GET
na adres URL źródła treści:
https://sites.google.com/feeds/content/site/siteName
Parametr kanału | Opis |
---|---|
site | „site ” lub domena Twojej hostowanej domeny G Suite (np. example.com ). |
siteName | Nazwa przestrzeni internetowej Twojej witryny, która znajduje się 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);
Powstały w ten sposób obiekt contentFeed
to obiekt ContentFeed
zawierający odpowiedź z serwera. Każdy wpis contentFeed
reprezentuje inną stronę lub inny element w witrynie użytkownika. ContentFeed
będzie zawierać różne typy obiektów dziedziczone z BaseContentEntry
: ListItemEntry
, ListPageEntry
, AttachmentEntry
, WebAttachmentEntry
, FileCabinetPageEntry
, AnnouncementsPageEntry
, AnnouncementEntry
, WebPageEntry
, CommentEntry
.
Oto przykład listy różnych typów wpisów w elemencie ContentFeed
.
Każdy typ wpisu ma inne właściwości, ale nie wszystkie są tutaj wymienione.
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 kanał może wymagać uwierzytelniania, w zależności od uprawnień do udostępniania danej witryny. Jeśli witryna nie jest publiczna, klient musi uwierzytelnić się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.
Przykłady zapytań dotyczących źródła treści
W źródle treści możesz przeszukiwać niektóre standardowe parametry zapytań interfejsu Google Data API oraz parametry charakterystyczne dla klasycznej wersji interfejsu Sites API. Szczegółowe informacje i pełną listę obsługiwanych parametrów znajdziesz w przewodniku.
Uwaga: w przykładach w tej sekcji korzystamy z metody buildContentFeedUrl()
opisanej w artykule Pobieranie źródła treści.
Pobieranie określonych rodzajów wpisów
Aby pobrać tylko określony typ wpisu, użyj parametru kind
. W tym przykładzie zwracamy tylko tyle wpisów: 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ż jeden typ wpisu, oddziel każdy element kind
znakiem „,”. W tym przykładzie zwracamy 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 stron według ścieżki
Jeśli znasz względną ścieżkę strony w Witrynach Google, możesz użyć parametru path
, aby pobrać tę konkretną stronę.
W tym przykładzie zostanie zwrócona strona 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 ze strony nadrzędnej
Jeśli znasz identyfikator wpisu treści strony (np. „1234567890” w podanym niżej przykładzie), możesz użyć parametru parent
do pobrania wszystkich jej wpisów podrzędnych (jeśli występują):
ContentQuery query = new ContentQuery(new URL(buildContentFeedUrl())); query.setParent("1234567890"); ContentFeed contentFeed = client.getFeed(query, ContentFeed.class);
Dodatkowe parametry znajdziesz w Przewodniku.
Tworzenie treści
Uwaga: zanim utworzysz treść witryny, upewnij się, że jest ona skonfigurowana w kliencie.client.site = "siteName";
Nowe treści (strony internetowe, strony z listami, strony do przechowywania plików, strony z ogłoszeniami itp.) można tworzyć, wysyłając żądania HTTP POST
do źródła treści:
https://sites.google.com/feeds/content/site/siteName
Listę typów węzłów pomocy znajdziesz w parametrze kind
w przewodniku.
Tworzenie nowych elementów / stron
W tym przykładzie tworzony jest nowy element webpage
w najwyższym poziomie witryny, zawierający w treści strony kod XHTML oraz tytuł nagłówka „Tytuł nowej 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 zrealizowane, createdEntry
będzie zawierać kopię wpisu utworzonego na serwerze.
Tworzenie elementów/stron w ramach niestandardowych ścieżek adresów URL
Domyślnie poprzedni przykład ma adres URL http://sites.google.com/site/siteName/new-webpage-title
i jego nagłówek to „Tytuł nowej strony internetowej”. Oznacza to, że parametr <atom:title>
jest znormalizowany w przypadku adresu URL do wartości new-webpage-title
.
Aby dostosować ścieżkę adresu URL strony, możesz ustawić element <sites:pageName>
.
W tym przykładzie tworzymy nową stronę filecabinet
o nagłówku „Magazyn plików”, ale strona ma URL http://sites.google.com/site/siteName/files
(zamiast http://sites.google.com/site/siteName/file-storage
) 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 tych reguł pierwszeństwa do nazewnictwa ścieżki adresu URL strony:
<sites:pageName>
(jeśli występuje). Musi spełniać następujące kryteria:a-z, A-Z, 0-9, -, _
.<atom:title>
, jeśli parametr pageName nie występuje, nie może mieć wartości null. Normalizacja polega na obcięciu i zwinięciu odstępów do znaku „-” oraz usuwaniu znaków, które nie pasują doa-z, A-Z, 0-9, -, _
.
Tworzenie podstron
Aby utworzyć podstronę (elementy podrzędne) pod stroną nadrzędną, musisz ustawić link nadrzędny we wpisie. Atrybut href
linku do własnego linku węzła nadrzędnego.
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());
Powyższy przykład powoduje utworzenie nowego elementu announcement
na stronie z pierwszymi ogłoszeniami znalezionej w źródle treści użytkownika. Tytuł ogłoszenia to „Impreza!!”, a jego treść to „Moje miejsce, w ten weekend”.
Szablony stron
Tworzenie szablonów stron
Proces tworzenia szablonu strony wygląda tak samo jak tworzenie nowych elementów/stron i tworzenie podstron.Różnica polega na dodaniu parametru category
z hasłem i etykietą ustawionymi odpowiednio na „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ć instancję nowej strony z szablonu, dodając element <link>
z atrybutem rel='http://schemas.google.com/sites/2008#template', który wskazuje własny link do szablonu strony.
Ten przykład tworzy nowy szablon filecabinet
, a następnie tworzy instancję nowej strony filecabinet
z tego szablonu.
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: mimo że szablon określa atrybut <category>
, wstawienie go w Twoim wpisie jest nadal wymagane. Pamiętaj też, że jeśli umieścisz element <content>
, serwer go odrzuci.
Przesyłam pliki
Podobnie jak w przypadku Witryn Google, interfejs API obsługuje przesyłanie załączników na stronę magazynu plików lub stronę nadrzędną.
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 należy przesyłać na stronę nadrzędną. Dlatego ustawiasz link nadrzędny w obiekcie AttachmentEntry
lub WebAttachmentEntry
, który próbujesz przesłać. Więcej informacji znajdziesz w artykule Tworzenie podstron.
Przesyłam załączniki
W tym przykładzie plik PDF został przesłany do pierwszego elementu FileCabinetPageEntry
znalezionego w źródle treści użytkownika.
Załącznik zostanie utworzony z tytułem „Pierwsze kroki” i (opcjonalnie) opisem „Pakiet kadr”.
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ę powiedzie, w pliku attachment
pojawi się kopia utworzonego załącznika.
Przesyłanie załącznika do folderu
Aby przesłać załącznik do istniejącego folderu w elemencie FileCabinetPageEntry
, dodaj kategorię z atrybutem „term” ustawionym na nazwę folderu.
Na przykład dodaj ten wiersz w 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. Są to więc linki do innych plików w internecie, które możesz dodać do magazynu plików. Ta funkcja działa analogicznie do metody przesyłania „Dodaj plik według adresu URL” w interfejsie Witryn Google.
Uwaga: załączniki internetowe można tworzyć tylko w magazynie plików. Nie można ich przesyłać na strony innego typu.
W tym przykładzie tworzony jest element WebAttachmentEntry
poniżej pierwszego elementu FileCabinetPageEntry
znalezionego w źródle treści użytkownika.
Jego tytuł i (opcjonalny) opis są ustawione na „Logo Google” 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!");
Element POST
tworzy link w magazynie plików użytkownika wskazujący obraz pod adresem „http://www.google.com/images/logo.gif”.
Aktualizowanie treści
Aktualizowanie metadanych strony lub treści HTML
Metadane (tytuł, nazwa strony itp.) i zawartość strony dowolnego typu BaseContentEntry
można edytować za pomocą metody update()
wpisu. Spowoduje to wysłanie żądania HTTP PUT
do linku edit
wpisu.
Poniżej znajduje się przykład zaktualizowania elementu ListPageEntry
za pomocą tych zmian:
- Tytuł został zmieniony na „Zaktualizowany tytuł”
- Zawartość HTML strony zostaje zaktualizowana do „<p>Updated HTML Content</p>” (Zaktualizowana treść HTML).
- Nagłówek pierwszej kolumny na liście 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 jego metody updateMedia(boolean)
.
Ten przykład spowoduje zaktualizowanie treści 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); }
W tym przykładzie wysyła żądanie HTTP PUT
do linku edit-media
wpisu. Zwrócony AttachmentEntry
będzie zawierać zaktualizowaną treść.
Aktualizowanie metadanych i treści załączników
Korzystając z metody updateMedia()
, możesz zaktualizować metadane i zawartość załącznika w tym samym wywołaniu.
Jeśli możesz zaktualizować tylko treść pliku, metadane lub oba te elementy.
W tym przykładzie zmienia się tytuł załącznika na „Nowy tytuł”, aktualizuje jego opis i zastępuje zawartość pliku nowym plikiem ZIP.
Żądanie zawiera nową treść pliku, dlatego używana jest zasada updateMedia()
z 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");
Usuwam treści
Aby usunąć stronę lub element z witryny Google, najpierw pobierz wpis treści, a następnie wywołaj jego właściwość delete()
.
entry.delete();
Możesz też użyć metody delete()
klasy usługi, przekazując jej link edit
wpisu i wartość ETag:
client.delete(entry.getEditLink().getHref(), "*"); // Note: using "*" may overwrite another client's changes.
Jeśli wpis został usunięty, serwer wysyła odpowiedź HTTP 200 OK
.
Pobieranie załączników
Aby pobrać element AttachmentEntry
, wyślij żądanie HTTP GET
do linku źródłowego treści wpisu.
W tym przykładzie pobierany jest pierwszy plik AttachmentEntry
znaleziony w źródle treści użytkownika do katalogu „/ścieżka/do/zapisania/pliku/”:
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.");
Kanał ACL
Omówienie uprawnień do udostępniania (listy kontroli dostępu)
Każdy wpis na liście kontroli dostępu (ACL) reprezentuje rolę dostępu określonego elementu: użytkownika, grupy użytkowników, domeny lub domyślnego dostępu (witryny publicznej). Wpisy będą wyświetlane tylko w przypadku jednostek z jednoznacznym dostępem. Dla każdego adresu e-mail będzie wyświetlany jeden wpis w panelu „Osoby z dostępem” na ekranie udostępniania w interfejsie Witryn Google. Z tego względu administratorzy domen nie będą widoczni, nawet jeśli mają pośredni dostęp do witryny.
Role
Element roli określa poziom dostępu, który może mieć encja. Element gAcl:role
może mieć 4 wartości:
- reader – przeglądający (odpowiednik dostępu tylko do odczytu).
- writer – współpracownik (odpowiednik uprawnień do odczytu i zapisu).
- właściciel – zwykle administrator witryny (odpowiednik uprawnień do odczytu i zapisu).
Zakresy
Element zakresu reprezentuje jednostkę, która ma ten poziom dostępu. Istnieją 4 rodzaje elementów gAcl:scope
:
- user – wartość adresu e-mail, np. „użytkownik@gmail.com”.
- grupa – adres e-mail Grupy dyskusyjnej Google, np. „grupa@domena.com”.
- domena – nazwa domeny G Suite, np. „domena.com”.
- default – istnieje tylko jeden możliwy zakres typu „default”, który nie ma żadnej wartości (np.
<gAcl:scope type="default">
). Ten konkretny zakres kontroluje domyślne uprawnienia dostępu każdego użytkownika do witryny publicznej.
Uwaga: domeny nie mogą mieć wartości gAcl:role
ustawionej na dostęp „właściciel”. Mogą to być tylko czytelnicy lub pisarze.
Pobieranie kanału ACL
Klasy AclFeed
i AclEntry
umożliwiają kontrolowanie uprawnień do udostępniania witryny i można je pobierać za pomocą metody getFeed()
klasy usługi.
Ten przykład pobiera kanał listy kontroli dostępu (ACL) dla danej witryny i wyświetla uprawnienia każdego z 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 pozycjami w pliku SiteFeed, każdy element SiteEntry
zawiera link do swojego kanału ACL.
Na przykład ten fragment pobiera kanał ACL dotyczący elementu 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: niektóre listy kontroli dostępu (ACL) mogą być dostępne tylko wtedy, gdy domena jest skonfigurowana tak, by zezwalać na takie uprawnienia (np.włączone jest udostępnianie poza domenę w przypadku domen G Suite itp.).
Aby udostępnić Witrynę Google za pomocą interfejsu API, Twój klient musi utworzyć nowy obiekt AclEntry
i POST
go przesłać do serwera.
Oto przykład dodania adresu „użytkownik@example.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 Omówienie pliku danych listy kontroli dostępu.
Udostępnianie na poziomie grupy i domeny
Podobnie jak w przypadku udostępniania witryny jednemu użytkownikowi, możesz udostępnić witrynę w grupie dyskusyjnej Google lub domenie G Suite.
Udostępnianie adresu e-mail grupy:
AclScope scope = new AclScope(AclScope.Type.GROUP, "group_name@example.com");
Udostępnianie w całej domenie:
AclScope scope = new AclScope(AclScope.Type.DOMAIN, "example.com");
Udostępnianie na poziomie domeny jest obsługiwane tylko w domenach G Suite i tylko w domenie, w której znajduje się witryna. Na przykład witryna http://sites.google.com/a/domena1.com/witrynaA może udostępnić całą witrynę tylko domenie domena1.com, a nie domena2.com. Witryny, które nie są hostowane w domenie G Suite (np. http://sites.google.com/witryna/witrynaB), nie mogą zapraszać domen.
Modyfikowanie uprawnień do udostępniania
Aby dodać istniejące uprawnienia do udostępniania witryny, najpierw pobierz dany AclEntry
, w razie potrzeby zmień uprawnienia, a następnie wywołaj metodę update()
narzędzia AclEntry
, aby zmodyfikować listę kontroli dostępu na serwerze.
Ten przykład modyfikuje poprzedni przykład dotyczący aclEntry
z sekcji Udostępnianie witryny przez zmianę adresu „użytkownik@example.com” na writer
(współpracownik):
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 klasach ETag znajdziesz w Przewodniku po interfejsach API danych Google.
Usuwanie uprawnień do udostępniania
Aby usunąć uprawnienia do udostępniania, najpierw pobierz 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 klasach ETag znajdziesz w Przewodniku po interfejsach API danych Google.
Tematy specjalne
Ponowne pobieranie kanału lub wpisu
Jeśli chcesz pobrać pobrany wcześniej kanał lub wpis, możesz zwiększyć wydajność, informując serwer, że ma wysłać listę lub wpis tylko wtedy, gdy zmieniły się od czasu ostatniego pobrania.
Aby przeprowadzić tego rodzaju pobieranie warunkowe, metody getFeed()
i getEntry()
zapewniają dodatkowy argument, który akceptuje wartość ETag lub obiekt DateTime
dla nagłówka If-Modified-Since
.
Dostęp do e-maila wpisu możesz uzyskać na stronie entry.getEtag()
.
W tym przykładzie wykonywane jest warunkowe pobieranie wpisu na stronie internetowej 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 taki sam tag ETag jak określony przez Ciebie tag ETag. Jeśli parametry ETag są zgodne, element nie uległ zmianie i serwer zwraca wyjątek NotModifiedException
HTTP 304.
Jeśli identyfikatory ETag nie są zgodne, oznacza to, że element został zmodyfikowany od ostatniego żądania tego żądania, a serwer go zwraca.
Więcej informacji o klasach ETag znajdziesz w Przewodniku po interfejsach API danych Google.