Начиная

Введение

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

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

Обзор

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

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

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

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

Получите учетную запись Google

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

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

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

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

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

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

Ваше приложение должно использовать OAuth 2.0 для авторизации запросов. Никакие другие протоколы авторизации не поддерживаются. Если ваше приложение использует Sign In With Google , некоторые аспекты авторизации выполняются за вас.

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

Все запросы к Google Site Verification API должны быть авторизованы пользователем, прошедшим проверку подлинности.

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

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

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

Вот информация о области действия OAuth 2.0 для Google Site Verification API:

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

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

Справочная информация об API проверки сайта Google

Концепции

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

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

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

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

Ограничения

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

• Доступ к данным только для аутентифицированного пользователя: все операции требуют аутентификации и авторизации пользователя.
• Проверка только для пользователя, прошедшего проверку подлинности: API может подтвердить право собственности на сайты или домены только для текущей учетной записи, прошедшей проверку подлинности. Однако пользователь, прошедший проверку подлинности, может делегировать право владения другим пользователям после подтверждения их права собственности на сайт. Обратите внимание, что все владельцы уведомляются по электронной почте всякий раз, когда в список владельцев вносятся изменения.
• Только нормализованные URL-адреса и доменные имена. Google Site Verification API не поддерживает кодировку 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-файл с токеном проверки Meta может выглядеть следующим образом:

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

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

Аналитика

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

Диспетчер тегов

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

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

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

Веб-ресурс

Google Site Verification API применяет семантику 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 проверки сайта.