Обзор интеграции

Сервис Local Services Ads (LSA) сотрудничает с агрегаторами для размещения их объявлений (или информации о поставщиках) на Google.com. В этом руководстве мы описываем, как агрегаторы могут предоставлять структурированные данные LSA о своих поставщиках. В частности, мы документируем набор конечных точек API, которые агрегаторы должны реализовать для интеграции с LSA.

Глоссарий

Агрегатор (или партнер) : это партнеры, которые объединяют поставщиков, которым они предоставляют услуги и чьи данные могут быть предоставлены LSA.

Поставщик услуг 3P (или листинг) : это отдельные малые предприятия (например, сантехника Джо), которые могут иметь деловые отношения с агрегаторами. Агрегаторы предоставляют местным службам информацию об этих предприятиях.

Обзор

Агрегаторы предоставляют данные о своих поставщиках (компаниях) в службу «Местные услуги» с помощью фидов. Каждый фид содержит данные о нескольких поставщиках. В фиде данные об одном поставщике инкапсулируются в элемент фида. Каждый фид также указывает временную метку фида, которая указывает на актуальность фида. Каждый фид также указывает тип фида: это могут быть данные о профиле поставщика или отзывы о нём, как описано ниже.

Типы кормов

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

  • Ленты профилей: эти фиды содержат информацию о профилях поставщиков. Каждый элемент фида содержит информацию о профиле конкретного поставщика. Сюда входят уникальный идентификатор компании, название компании, адреса обслуживания, предлагаемые услуги, часы работы и т. д. Элемент фида также содержит метаданные об обслуживании для этой компании (например, размер ежемесячного бюджета, статус объявления и т. д.).

  • Ленты отзывов: Эта лента содержит информацию об отзывах о поставщиках. Каждый элемент ленты содержит список подробных отзывов потребителей о конкретном поставщике. Каждый отзыв потребителя состоит из имени потребителя, рейтинга (1–5), текста отзыва, даты и времени написания отзыва и т. д.

Более подробная информация о конкретных полях и их семантике представлена в Ленте профилей и Ленте отзывов .

Прием корма

Данные фида сериализуются в формате JSON. Для отправки данных LSA поддерживает только механизм pull. В будущем планируется поддержка механизма push.

Тяговый механизм

В механизме pull агрегаторы поддерживают набор предопределённых конечных точек REST (URL), которые отправляют и получают JSON-объекты. Это аналогично размещению одного или нескольких файлов на веб-сервере. LSA периодически отправляет HTTP-запросы GET к этим URL для извлечения данных. Подробную информацию о предопределённых URL можно найти в следующем разделе, посвящённом конечным точкам API.

Нажимной механизм

В механизме push-запросов LSA предоставляет конечную точку, к которой агрегаторы могут обращаться и предоставлять данные. Семантически это то же самое, что и pull-запрос, но обеспечивает гибкость в случаях, когда агрегаторы хотят передать определённые данные в локальные сервисы. Вся семантика, правила и ограничения, описанные в протоколе, применяются одинаково как к push-запросам, так и к pull-запросам.

конечные точки API

Агрегаторы должны поддерживать следующие конечные точки: одну для ленты профилей и одну для ленты отзывов.

Мы рекомендуем, чтобы конечные точки содержали информацию о версии, как показано ниже. Начнём с v1 .

Конечная точка Путь
Лента профилей /feeds/{version}/profile
Лента отзывов /feeds/{version}/review

Параметры конечной точки

Параметры Описание
maxresults Это ограничение на количество элементов ленты, которые можно запросить на странице.
nextpagetoken Токен пагинации для получения следующей страницы результатов

Аутентификация конечной точки

Для аутентификации используется базовый HTTP-доступ: имя пользователя и пароль, закодированные в формате base64. Ниже приведён пример.

  • username «Авторизация» (для наглядности)
  • password J9adfdsafc3RfMjpVU1yif5XMw» (для наглядности)

SFTP-аккаунт для Push-уведомлений

Путь Dropbox: partnerupload.google.com:19321

ВНИМАНИЕ: файлы, загруженные в этот почтовый ящик SFTP, автоматически удаляются через 24 часа.

Аутентификация конечной точки

  • Пара открытого и закрытого ключей (рекомендуется)

    • Воспользуйтесь этим руководством для генерации пар ключей.
    • Отправьте LSA открытый ключ и сохраните закрытый ключ для аутентификации.
    • LSA будет использовать открытый ключ для генерации имени пользователя и отправки обратно агрегатору.

  • Аутентификация по паролю

    • LSA сгенерирует имя пользователя и пароль и отправит их обратно агрегатору.

Краткий справочник по командам SFTP

  1. Войти. Используйте эту команду для входа. (Не указывайте -i если вы не используете закрытый ключ).

    sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

  2. Копировать файл. Скопируйте файл в удалённую систему. Вы можете использовать lls/lcd и ls/cd в локальной системе, чтобы найти файл. Затем скопируйте файл с помощью:

    put <path_to_local_file>

  3. Проверьте. Используйте ls , чтобы просмотреть список папок и файлов в каталоге SFTP и убедиться, что ваш файл скопирован на удалённую систему.

Категории кормов

Как отмечалось ранее, каждый фид аналогичен файлу и состоит из нескольких элементов фида. Каждый элемент фида содержит данные о конкретном поставщике (уникальный идентификатор компании). Каждый фид также имеет временную метку, которая указывает на актуальность фида. Категория фида определяет, как LSA интерпретирует данный фид. Существует две категории фидов, описанные ниже.

Лента снимка содержит полный список поставщиков (в рамках агрегатора) на определённую временную метку. После обработки этой ленты снимка применяется следующая семантика:

  • Для любого поставщика, присутствующего в фиде, система обновит данные по этому поставщику в базе данных LSA (например, создаст нового поставщика, если он обнаружен впервые, или обновит данные о поставщике, если поставщик был обработан в более раннем фиде).

  • Для любого поставщика, работающего в агрегаторе и присутствующего в настоящее время в базе данных LSA, но отсутствующего в фиде, поставщик будет удален.

Фид обновлений (или инкрементный фид) содержит частичный список поставщиков (в рамках агрегатора) на определённую временную метку. После обработки инкрементного фида применяется следующая семантика:

  • Для любого поставщика, присутствующего в канале, система обновит данные по этому поставщику в базе данных LSA, если поставщик был создан в более раннем канале моментальных снимков. (например, если поставщик встречается впервые, это будет пустая операция)

  • Для любого поставщика, который в настоящее время присутствует в базе данных LSA, но отсутствует в фиде, это не будет выполнено (т.е. никаких изменений для этого поставщика не произойдет).

Семантика фидов профилей и отзывов имеет некоторые нюансы. Подробности обработки см. в семантике отдельных фидов.

Ленты профилей: * Ленты снимков на основе pull-данных * Ленты снимков на основе push-данных * Ленты обновлений на основе push-данных Ленты обзоров: * Ленты снимков на основе pull-данных * Ленты снимков на основе push-данных

Отдельные фиды профилей требуются для:

  1. Поставщики, которые имеют право на получение Гарантии Google или значка Google Screened .

  2. Поставщики, не имеющие права на получение значка.

Примеры

Ленты моментальных снимков

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

Как это работает

Ниже приведен простой пример, демонстрирующий, как работает категория снимков профилей.

  • Снимок 1 имеет Pro 1, Pro 2
  • Снимок 2 имеет Pro 1, Pro 3

После обработки снимка 1 в базе данных LSA будут Pro 1 и Pro 2. Во время обработки снимка 2 LSA обновит Pro 1, создаст Pro 3 и удалит Pro 2. То есть после обработки снимка 2 в базе данных LSA будут Pro 1 и Pro 3.

Обновление (инкрементное) каналов

Напомним, что лента обновлений содержит частичный список поставщиков агрегатора. Например, если агрегатор хочет обновить только 5 из 100 ранее предоставленных им поставщиков, лента обновлений должна содержать только последние данные об этих 5 поставщиках.

Как это работает

Ниже приведен простой пример, демонстрирующий, как работает категория обновлений «ленты профилей».

  • Обновление 1: Pro 1, Pro 2
  • Обновление 2: Pro 1, Pro 3

После обработки обновления 1 в базе данных LSA будут Pro 1 и Pro 2. Во время обработки обновления 2 LSA обновит Pro 1 и создаст Pro 3. Обратите внимание, что Pro 2 останется нетронутым. То есть после обработки обновления 2 в базе данных LSA будут Pro1, Pro2 и Pro 3.

Последствия метода «снимок» и «вытягивание»

Механизм snapshot feeds + pull подразумевает следующие ограничения:

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

Последствия инкрементальной и push-поддержки

Открытие каналов обновлений + механизм push-уведомлений подразумевает следующие улучшения:

  • Партнеры могут предоставлять снимки данных в режиме push или pull. Партнеры, которые предпочитают не обслуживать конечную точку (для pull), могут использовать push для снижения затрат на обслуживание конечной точки. Партнеры, уже поддерживающие снимки данных в режиме pull, могут продолжать предоставлять снимки в режиме pull.
  • Партнеры могут использовать инкрементные обновления только для подмножества поставщиков, в которых произошли изменения в профилях. Это повышает актуальность данных профилей.
  • Что касается выбора между моментальными снимками и инкрементными копиями, push и pull, см. этот раздел для получения информации о рекомендуемом подходе к интеграции.

Партнёрам необходимо периодически получать снимки состояния, как по запросу, так и по запросу. Это позволяет LSA обрабатывать экстренные ситуации, такие как откат и восстановление системы в случае пропущенных обновлений.

  • При использовании механизма push-уведомлений партнеры должны отправлять каналы профилей снимков каждые 2 часа и просматривать каналы каждые 6 часов, чтобы гарантировать актуальность исходных данных.
  • Благодаря механизму извлечения LSA будет извлекать каналы профилей снимков каждые 2 часа и просматривать каналы каждые 6 часов, чтобы гарантировать актуальность исходных данных.
  • Для предоставления мгновенных снимков партнерам нужен только один из механизмов (либо push, либо pull), но не оба сразу.

При желании партнёры, желающие повысить актуальность данных, могут отправлять каналы обновлений через push-уведомления. LSA не будет загружать каналы обновлений.

  • Каналы обновлений используются для распространения измененных элементов с момента последнего снимка, не дожидаясь следующего снимка.
  • LSA рекомендует поставщикам услуг устанавливать интервал более 5 минут между двумя нажатиями.
  • Рекомендуется разумно объединять элементы фида в один фид обновлений. Для обновления пяти поставщиков LSA рекомендует поставщикам отправлять один фид обновлений с пятью элементами фида, а не пять фидов обновлений с одним элементом в каждом.
  • LSA поддерживает инкрементные каналы только для каналов профилей, но не для каналов обзоров.

LSA будет учитывать поле feedTimestampMicros в метаданных для обеспечения согласованности данных. Элемент фида с более старой временной меткой будет пропущен, чтобы избежать устаревания данных, если был загружен более новый элемент, обновляющий тот же продукт. Партнёр обязан корректно отражать актуальность данных с помощью поля feedTimestampMicros как в моментальных снимках, так и в обновлениях.

Партнеры должны использовать API отчетности для получения информации о потенциальных клиентах и расходах по каждому поставщику.