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

В этом документе подробно описаны базовые знания, необходимые для использования API проверки сайта Google.

Введение

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

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

Обзор

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

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

В качестве конкретного примера использования этого API предположим, что вы предоставляете услугу веб-хостинга. Ваши пользователи хотят иметь возможность использовать консоль поиска Google для получения информации о своем сайте. Чтобы это сделать, Google должен знать, что он действительно владеет им. Таким образом, вы предоставляете своим пользователям интерфейс, который просит их подтвердить право собственности на сайт. Они предоставляют вашему приложению доступ к своим проверочным данным, и теперь оно может выполнять код, который запрашивает токен от их имени, помещает его в файл в структуре своего сайта и просит Google проверить его. Когда Google находит токен, он передает право собственности на сайт пользователю, обновляя его проверочные данные. Теперь они могут использовать Search Console для получения нужной информации.

Прежде чем начать

Получить аккаунт Google

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

Ознакомьтесь с проверкой сайта

Если вы не знакомы с концепциями API проверки сайта Google, вам следует прочитать этот документ, поэкспериментировать с пользовательским интерфейсом проверки и прочитать соответствующую справочную документацию, прежде чем приступать к написанию кода.

Узнайте, как авторизовать запросы

Каждый запрос, который ваше приложение отправляет в API проверки сайта Google, должен включать токен авторизации. Токен также идентифицирует ваше приложение для Google.

О протоколах авторизации

Ваше приложение должно использовать OAuth 2.0 для авторизации запросов. Другие протоколы авторизации не поддерживаются. Если ваше приложение использует «Войти через Google» , некоторые аспекты авторизации выполняются за вас.

Авторизация запросов с помощью OAuth 2.0

Все запросы к API проверки сайта Google должны быть авторизованы авторизованным пользователем.

Детали процесса авторизации или «потока» для OAuth 2.0 несколько различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применим ко всем типам приложений:

  1. Когда вы создаете свое приложение, вы регистрируете его с помощью консоли Google API . Затем Google предоставляет информацию, которая понадобится вам позже, например идентификатор клиента и секрет клиента.
  2. Активируйте API проверки сайта Google в консоли API Google. (Если API не указан в консоли API, пропустите этот шаг.)
  3. Когда вашему приложению требуется доступ к пользовательским данным, оно запрашивает у Google определенный объем доступа.
  4. Google отображает пользователю экран согласия , прося его разрешить вашему приложению запрашивать некоторые из его данных.
  5. Если пользователь одобряет, Google предоставляет вашему приложению кратковременный токен доступа .
  6. Ваше приложение запрашивает пользовательские данные, прикрепляя к запросу токен доступа.
  7. Если Google определит, что ваш запрос и токен действительны, он вернет запрошенные данные.

Некоторые потоки включают дополнительные шаги, например использование токенов обновления для получения новых токенов доступа. Подробную информацию о потоках для различных типов приложений см. в документации Google OAuth 2.0 .

Ниже представлена ​​информация об области действия OAuth 2.0 для API проверки сайта Google:

Объем Значение
https://www.googleapis.com/auth/siteverification Полный доступ для чтения существующих проверенных сайтов, возможность проверять новые сайты.
https://www.googleapis.com/auth/siteverification.verify_only Возможность проверять новые сайты, без доступа для чтения существующих проверенных сайтов.

Чтобы запросить доступ с помощью OAuth 2.0, вашему приложению необходима информация об области действия, а также информация, которую Google предоставляет при регистрации вашего приложения (например, идентификатор клиента и секрет клиента).

Совет: Клиентские библиотеки API Google могут выполнить за вас часть процесса авторизации. Они доступны для различных языков программирования; проверьте страницу с библиотеками и образцами для получения более подробной информации.

История API проверки сайта Google

Концепции

Вы можете использовать API проверки сайта Google, чтобы установить право собственности пользователя на следующие типы веб-ресурсов:

  • Домен: Домен или субдомен. Владельцем домена считается владелец всех сайтов и поддоменов в этом домене. Например, прямой владелец bar.com также считается косвенным владельцем foo.bar.com .
  • Сайт: URL-адрес, соответствующий базовому домену и пути к веб-сайту. Владельцем сайта считается владелец всех сайтов, входящих в его состав. Например, владелец «http://www.example.com/site» также считается владельцем «http://www.example.com/site/subsite».

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

Процесс установления права собственности начинается с того, что ваше приложение запрашивает «токен проверки» от имени пользователя. Токен подтверждения — это специальная строка, которую ваш код затем должен разместить на своем веб-сайте или в домене. После того как токен будет установлен, ваше приложение может отправить запрос к API проверки сайта Google, который проверяет наличие токена и записывает право собственности, когда он найден.

Ограничения

По соображениям безопасности и техническим причинам Google Site Verification API налагает некоторые ограничения на его использование:

  • Доступ к данным только для аутентифицированного пользователя: все операции требуют аутентификации и авторизации пользователя.
  • Проверка только для аутентифицированного пользователя: API может проверять право собственности на сайты или домены только для текущей аутентифицированной учетной записи. Однако прошедший проверку подлинности пользователь может делегировать право собственности другим пользователям после того, как его право собственности на сайт будет подтверждено. Обратите внимание, что все владельцы уведомляются по электронной почте обо всех изменениях в списке владельцев.
  • Только нормализованные URL-адреса и доменные имена. API проверки сайта Google не поддерживает кодировку IDN (международное доменное имя). Обязательно нормализуйте все URL-адреса, доменные имена и домены адресов электронной почты в соответствии со стандартным набором символов доменного имени (RFC 1034 §3.5), используя Punycoding, если необходимо.

Методы проверки и токены

API обеспечивает вызовы для отдельных этапов проверки:

  • Размещение токена проверки. Существует вызов API для получения токена проверки для размещения на сайте аутентифицированного пользователя. Если у пользователя более одного сайта, вам необходимо получить отдельный токен для каждого сайта.
  • Проверка наличия токена проверки. Существует отдельный вызов API, который запрашивает у Google проверку токена, чтобы убедиться, что аутентифицированный пользователь владеет сайтом.

Существует несколько способов проверки веб-сайта или домена, который может использовать ваше приложение; тот, который вы выберете, зависит от того, что лучше всего соответствует вашим требованиям. Место размещения токена, а также тип самого токена зависит от того, какой метод проверки вы выберете.

Метод проверки домена

Для доменов доступны два метода проверки:

DNS_CNAME

Ваше приложение создает новую запись CNAME для домена владельца, возможно, через регистратора домена, используя токен для данных записи. Токен состоит из двух частей, разделенных пробелом: первая часть — это имя новой записи CNAME, вторая часть — значение новой записи CNAME.

DNS_TXT

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

Дополнительную информацию см. в документации Справочного центра по методу проверки DNS .

Методы проверки сайта

Для сайтов доступны три метода проверки:

Файл
Ваше приложение размещает токен в виде файла на веб-сайте владельца. Вы должны создать файл с именем, соответствующим строке токена, со следующим содержимым:
google-site-verification: token

Например, если сайт http://www.example.com/ принадлежит пользователю, а возвращаемый токен — google12cfc68677988bb4.html , вам просто нужно создать файл по адресу http://www.example.com/google12cfc68677988bb4. html (на верхнем уровне их сайта) со следующим содержимым:

google-site-verification: google12cfc8677988bb4.html

Дополнительную информацию см. в документации Справочного центра по методу проверки файлов .

Мета

Ваше приложение вставляет токен в виде HTML-тега <meta> в элемент <head> файла по умолчанию (index.html, default.html и т. д.) на верхнем уровне сайта владельца. HTML-файл с мета-токеном проверки может выглядеть так:

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

Дополнительную информацию см. в документации справочного центра по методу мета-верификации .

Аналитика

Ваше приложение использует существующий код отслеживания Google Analytics , который уже находится на веб-сайте владельца. Для работы код отслеживания должен принадлежать их аккаунту Google Analytics, а фрагмент должен находиться в теге HEAD. Дополнительную информацию см. в документации Справочного центра по методу проверки Analytics .

Менеджер тегов

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

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

Модель данных

Веб-ресурс

API проверки сайта Google применяет семантику REST (HTTP GET , POST и т. д.) к объектам, называемым веб-ресурсами. Веб-ресурс — это веб-сайт или домен, принадлежащий аутентифицированному пользователю.

Вот пример веб-ресурса:

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

Поле id — это уникальный идентификатор данного веб-ресурса. Вы используете его для ссылки на этот конкретный веб-ресурс для поиска и изменения. Сохраните поле id из выходных данных операции списка для последующего использования в качестве идентификатора.

Объект site содержит URL-адрес веб-ресурса или имя домена, а также тип ресурса. Сайты указываются с типом SITE ; домены указываются с типом INET_DOMAIN .

Массив owners — это полный список владельцев веб-ресурса, представленный их адресами электронной почты. Добавляя или удаляя адреса электронной почты из списка владельцев, прошедший проверку подлинности пользователь может предоставить совместное владение или отозвать право собственности у других пользователей. Дополнительные владельцы, разместившие собственные токены на сайте или домене, также отображаются в списке владельцев вместе со своими совладельцами.

Пользователи, которым предоставлено совместное владение, также могут предоставить совместное владение, если на сайте есть хотя бы один подтвержденный владелец с токеном.

Коллекция веб-ресурсов

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

Как было указано ранее в разделе «Ограничения» , веб-ресурсы, принадлежащие другим пользователям, кроме прошедших проверку подлинности, недоступны через API проверки сайта.