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

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

Глоссарий

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

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

Обзор

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

Типы фидов

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

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

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

Дополнительные сведения о конкретных полях и их семантике см. в ленте профиля и ленте отзывов .

Подача корма

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

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

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

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

В механизме push LSA предоставит агрегаторам конечную точку для вызова и предоставления данных. Семантически это то же самое, что и извлечение, но обеспечивает гибкость в тех случаях, когда агрегаторы хотят передать определенные данные в локальные службы. Вся семантика, правила или ограничения, описанные в протоколе, одинаково применимы как к 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. Копировать файл. Скопируйте файл в удаленную систему. Вы можете использовать ls lls/lcd для ls/cd в вашей локальной системе, чтобы найти файл. Затем скопируйте файл через:

    put <path_to_local_file>

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

Категории каналов

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

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

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

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

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

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

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

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

Каналы профилей: * Каналы снэпшотов на основе запроса * Ленты снэпшотов на основе push * Ленты обновлений на основе push Фиды обзоров: * Каналы снэпшотов на основе pull * Ленты снэпшотов на основе push

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

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

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

Примеры

Каналы снимков

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

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

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

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

После обработки Snapshot 1 база данных LSA будет иметь Pro 1 и Pro 2. Во время обработки Snapshot 2 LSA обновит Pro 1, создаст Pro 3 и удалит Pro 2. То есть после обработки Snapshot 2 в базе данных LSA будет Pro 1 и Про 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 останется нетронутым. То есть после обработки Update 2 в базе данных LSA будут Pro1, Pro2 и Pro 3.

Последствия Snapshot и Pull

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

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

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

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

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

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

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

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

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

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

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