Pierwsze kroki

Ten dokument zawiera podstawowe informacje niezbędne do korzystania z interfejsu Google Site Verification API.

Wstęp

Interfejs Google Weryfikacja API jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje lub usługi, które automatyzują proces weryfikacji własności witryny lub domeny. Ta wartość jest ważna, ponieważ z niektórych usług Google mogą korzystać tylko właściciele witryn lub domen. Za pomocą interfejsu Google Site Verification API możesz sprawdzić, czy uwierzytelniony użytkownik jest właścicielem domeny lub witryny, co prawdopodobnie jest pierwszym krokiem automatycznego udostępniania innych usług Google.

Zakładamy, że znasz programowanie i formaty danych z sieci oraz potrafisz programowo modyfikować pliki lub rekordy DNS witryny albo domeny.

Opis

Za pomocą interfejsu Google Site Verification API możesz modyfikować dane przesyłane przez użytkowników do weryfikacji witryny w Google. Użytkownicy mogą korzystać z niektórych usług Google tylko wtedy, gdy z danych weryfikacyjnych wynika, że są one właścicielami określonej domeny witryny. Za pomocą interfejsu API możesz generować tokeny weryfikacyjne dla uwierzytelnionych użytkowników, których kod może być umieszczany w Twoich witrynach lub rekordach domeny w różny sposób. Po umieszczeniu tokena wywołujesz interfejs API, aby poprosić Google o jego sprawdzenie. Jeśli Google znajdzie token, rejestruje uwierzytelnionego użytkownika jako właściciela witryny lub domeny. Za pomocą interfejsu API możesz też zmodyfikować listę własności w imieniu użytkownika lub całkowicie usunąć własność witryny.

Wszystkie wywołania interfejsu API muszą być autoryzowane przez uwierzytelnionego użytkownika, a wszystkie wywołania interfejsu API są wykonywane w kontekście konta uwierzytelnionego użytkownika.

Konkretnym przykładem wykorzystania tego interfejsu API może być usługa hostingu WWW. Użytkownicy chcą mieć dostęp do informacji o swojej witrynie w Search Console. Aby to było możliwe, Google musi wiedzieć, że jest to prawdziwa właścicielka. Dlatego musisz udostępnić użytkownikom interfejs z prośbą o potwierdzenie własności witryny. Dają one Twojej aplikacji dostęp do danych weryfikacyjnych i mogą wykonać kod, który w Twoim imieniu żąda tokenu, umieszcza go w pliku w strukturze witryny i prosi Google o sprawdzenie. Gdy Google znajdzie ten token, przyzna użytkownikowi uprawnienia do własności witryny, aktualizując swoje dane weryfikacyjne. Może teraz używać Search Console do uzyskiwania potrzebnych informacji.

Zanim rozpoczniesz

Załóż konto Google

Upewnij się, że masz konto Google. Zalecamy używanie oddzielnego konta Google do celów programistycznych i testowych, by chronić się przed przypadkową utratą danych.

Informacje o weryfikacji witryny

Jeśli nie masz doświadczenia w korzystaniu z interfejsu Google Site Verification API, przeczytaj ten dokument, poeksperymentuj z interfejsem weryfikacji oraz przeczytaj powiązaną z nim dokumentację pomocy.

Dowiedz się, jak autoryzować żądania

Każde żądanie wysyłane przez aplikację do interfejsu Google Site Verification API musi zawierać token autoryzacji. Token stanowi też dla Google identyfikator aplikacji.

Informacje o protokołach autoryzacji

Twoja aplikacja musi autoryzować żądania za pomocą protokołu OAuth 2.0. Nie są obsługiwane żadne inne protokoły. Jeśli aplikacja używa funkcji Zaloguj się przez Google, możesz załatwiać niektóre aspekty autoryzacji.

Autoryzowanie żądań za pomocą protokołu OAuth 2.0

Wszystkie żądania wysyłane do interfejsu Google Site Verification API muszą być autoryzowane przez użytkownika.

Szczegóły procesu autoryzacji z użyciem protokołu OAuth 2.0 różnią się nieznacznie w zależności od rodzaju projektowanej aplikacji. Do większości typów aplikacji ma zastosowanie ten ogólny proces:

  1. Gdy tworzysz aplikację, rejestrujesz ją, korzystając z konsoli interfejsów API Google. Następnie Google przekazuje informacje, które są potrzebne później, takie jak identyfikator klienta i tajny klucz klienta.
  2. Aktywuj interfejs Google Site Verification API w konsoli interfejsu Google API. (jeśli interfejsu API nie ma na liście w konsoli, pomijasz ten krok).
  3. Gdy Twoja aplikacja potrzebuje dostępu do danych użytkownika, prosi Google o konkretny zakres dostępu.
  4. Google wyświetla użytkownikowi ekran zgody z prośbą o autoryzowanie dostępu aplikacji do niektórych danych.
  5. Jeśli użytkownik wyrazi zgodę, Google przekazuje Twojej aplikacji ważny przez krótki czas token dostępu.
  6. Aplikacja żąda danych użytkownika i dołącza do żądania token dostępu.
  7. Jeśli Google uzna, że żądanie i token są prawidłowe, przesyła dane, o które prosisz.

Niektóre procesy obejmują dodatkowe kroki, takie jak wykorzystanie tokenów odświeżania do uzyskania nowych tokenów dostępu. Szczegółowe informacje o procesach obowiązujących w przypadku różnych typów aplikacji znajdziesz w dokumencie Google na temat protokołu OAuth 2.0.

Informacje o zakresie OAuth 2.0 interfejsu Google Site Verification API:

Zakres Znaczenie
https://www.googleapis.com/auth/siteverification Pełne uprawnienia do odczytu istniejących witryn, możliwość weryfikacji nowych witryn.
https://www.googleapis.com/auth/siteverification.verify_only możliwość weryfikowania nowych witryn, brak możliwości odczytu istniejących witryn,

Aby poprosić o dostęp przy użyciu protokołu OAuth 2.0, aplikacja potrzebuje danych z zakresu oraz informacji przekazywanych przez Google po zarejestrowaniu aplikacji (takich jak identyfikator klienta i tajny klucz klienta).

Wskazówka: biblioteki klienta interfejsów API Google mogą wykonać niektóre procesy autoryzacji za Ciebie. Są dostępne dla różnych języków programowania. Więcej szczegółów znajdziesz na stronie z bibliotekami i próbkami.

Tło interfejsu Google Site Verification API

Pojęcia

Za pomocą interfejsu Google Site Verification API możesz określić, kto jest właścicielem tych typów zasobów internetowych:

  • Domena: domena lub subdomena. Właściciel domeny jest uznawany za właściciela wszystkich witryn i subdomen w tej domenie. Na przykład bezpośredni właściciel firmy bar.com jest też uważany za pośredniego właściciela witryny foo.bar.com.
  • Witryna: adres URL odpowiadający domenie podstawowej i ścieżce witryny. Właściciel witryny jest uznawany za właściciela wszystkich należących do niej witryn. Właściciel witryny „http://www.example.com/site” jest też uważany za właściciela „http://www.example.com/site/podwitryna”.

Własność domeny ma szerokie zastosowanie w porównaniu z właścicielem witryny, dlatego w miarę możliwości zalecamy potwierdzanie własności domeny.

Proces ustalenia własności zaczyna się od wysłania w imieniu użytkownika wniosku o „token weryfikacyjny”. Token weryfikacyjny to specjalny ciąg znaków, który należy umieścić na stronie lub w domenie. Po zastosowaniu tokena aplikacja może wysłać żądanie do interfejsu Google Site Verification API, aby sprawdzić, czy token został znaleziony.

Ograniczenia

Ze względów bezpieczeństwa i technicznych interfejs Google Site Verification API wymusza pewne ograniczenia w sposobie jego użycia:

  • Dostęp do danych tylko uwierzytelniony użytkownik: wszystkie operacje wymagają uwierzytelnienia i autoryzacji użytkownika.
  • Weryfikacja tylko dla uwierzytelnionego użytkownika: interfejs API może zweryfikować tylko własność witryn lub domen obecnie uwierzytelnionego konta. Uwierzytelniony użytkownik może jednak przekazać własność innym użytkownikom po zweryfikowaniu własności witryny. Pamiętaj, że wszyscy właściciele otrzymają e-maila z powiadomieniem o każdej zmianie na liście własności.
  • Tylko znormalizowane adresy URL i nazwy domen. Interfejs Google Weryfikacja API nie obsługuje kodowania IDN (International Domain Name). Pamiętaj, aby w razie potrzeby znormalizować wszystkie adresy URL, nazwy domen i domeny adresów e-mail do standardowego zestawu znaków nazwy domeny (RFC 1034 § 3.5) przy użyciu funkcji Punycode.

Metody i tokeny weryfikacyjne

Interfejs API udostępnia wywołania na poszczególnych etapach weryfikacji:

  • Umieszczanie tokena weryfikacyjnego: w celu pobrania tokena weryfikacyjnego przez umieszczenie uwierzytelnionego użytkownika na stronie jest wykonywane wywołanie API. Jeśli użytkownik ma kilka witryn, musisz uzyskać inny token dla każdej z nich.
  • Sprawdzanie obecności tokena weryfikacyjnego: Google używa osobnego wywołania interfejsu API z prośbą o sprawdzenie, czy token jest właścicielem witryny.

Jest kilka metod weryfikacji witryny lub domeny, z których może korzystać Twoja aplikacja. Wybrana metoda zależy od tego, która z nich najlepiej spełnia Twoje wymagania. Miejsce umieszczenia tokena oraz typ tokena zależą od wybranej metody weryfikacji.

Metoda weryfikacji domeny

Dostępne są 2 metody weryfikacji domen:

DNS_CNAME

Twoja aplikacja utworzy nowy rekord CNAME dla domeny właściciela, np. u rejestratora domen, używając tokena danych rekordu. Token składa się z dwóch części rozdzielonych spacją: pierwsza to nowa nazwa rekordu CNAME, a druga to wartość nowego rekordu CNAME.

DNS_TXT

Twoja aplikacja utworzy nowy rekord TXT dla domeny właściciela, np. u rejestratora domeny, używając tokena danych rekordu.

Więcej informacji znajdziesz w dokumentacji Centrum pomocy dotyczącej metody weryfikacji DNS.

Metody weryfikacji witryn

W przypadku witryn dostępne są trzy metody weryfikacji:

Plik
Aplikacja umieszcza token w postaci pliku w witrynie właściciela. Musisz utworzyć plik o nazwie pasującej do ciągu tokena z tą zawartością:
google-site-verification: token

Jeśli na przykład użytkownik jest właścicielem witryny http://www.example.com/, a zwrócony token to google12cfc68677988bb4.html, musisz utworzyć plik pod adresem http://www.example.com/google12cfc68677988bb4.html (na najwyższym poziomie witryny) z tą zawartością:

google-site-verification: google12cfc8677988bb4.html

Więcej informacji znajdziesz w dokumentacji w artykule Metoda weryfikacji pliku.

Meta

Aplikacja umieszcza token w formie tagu HTML <meta> w elemencie <head> pliku domyślnego (index.html, default.html itd.) na najwyższym poziomie witryny właściciela. Plik HTML z tokenem weryfikacyjnym Meta może wyglądać tak:

<html>
  <head>
    <title>Awesome Dive Sites</title>
    <meta name="google-site-verification" content="-dhsoFQadgDKJR7BsB6bc1j5yfqjUpg_b-1pFjr7o3x" />
  </head>
  <body>
    ...

Więcej informacji znajdziesz w dokumentacji Centrum pomocy w artykule na temat metody weryfikacji Meta.

Analytics

Aplikacja używa istniejącego kodu śledzenia Google Analytics, który już znajduje się w witrynie właściciela. Kod śledzenia musi należeć do konta Analytics, a fragment kodu musi znajdować się w tagu HEAD, aby działał. Więcej informacji znajdziesz w Centrum pomocy w artykule o metodach weryfikacji Analytics.

Menedżer tagów

Aplikacja wykorzystuje istniejący kod kontenera Menedżera tagów Google, który już znajduje się w witrynie właściciela. Kod kontenera musi należeć do konta Menedżera tagów. Więcej informacji znajdziesz w dokumentacji Centrum pomocy dotyczącej metody weryfikacji Menedżera tagów.

Jeśli chcesz najpierw zweryfikować kilka witryn ręcznie w interfejsie weryfikacji witryny, możesz lepiej poznać podstawowe zagadnienia i procesy weryfikacji.

Model danych

Zasób internetowy

Interfejs API Google do weryfikacji witryny stosuje semantykę REST (HTTP GET, POST itd.) do jednostek nazywanych zasobami internetowymi. Zasób internetowy to witryna lub domena, która należy do uwierzytelnionego użytkownika.

Oto przykład zasobu internetowego:

{
  "owners": [
    "myself@example.com",
    "another@example.com"
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

Pole id to unikalny identyfikator tego zasobu internetowego. Wykorzystywana jest przez Ciebie w celu pobierania i modyfikowania tego konkretnego zasobu internetowego. Zapisz pole id z danych wyjściowych operacji listy na później jako identyfikator.

Obiekt site zawiera adres URL zasobu internetowego lub nazwę domeny, a także typ zasobu. Witryny są określone w typie SITE, a domeny mają typ INET_DOMAIN.

Tablica owners to pełna lista właścicieli zasobu internetowego reprezentowana przez ich adresy e-mail. Dodanie lub usunięcie adresów e-mail z listy właścicieli powoduje, że uwierzytelniony użytkownik może współdzielić z innymi użytkownikami prawo własności lub je unieważnić. Dodatkowi właściciele, którzy sami umieścili własne tokeny w witrynie lub domenie, pojawiają się na liście właścicieli razem z ich właścicielami.

Użytkownicy mogą zostać współwłaścicielami, o ile w witrynie jest co najmniej 1 zweryfikowany właściciel z tokenem.

Kolekcja zasobów internetowych

Kolekcja zasobów internetowych to pełna lista wszystkich zasobów internetowych należących do uwierzytelnionego użytkownika. Możesz zweryfikować własność witryn lub domen, próbując dodać nowe zasoby do uwierzytelnionego zbioru zasobów internetowych uwierzytelnionego użytkownika. Do kolekcji zostały dodane tylko zweryfikowane witryny lub domeny.

Jak wspomnieliśmy wcześniej w sekcji Ograniczenia, zasoby internetowe należące do użytkowników innych niż uwierzytelniony użytkownik nie mają dostępu do interfejsu Site Verification API.