Google.com에 목록 (또는 제공업체)을 표시하기 위해 애그리게이터와 파트너십을 맺는 지역 서비스 광고(LSA). 이 가이드에서는 애그리게이터가 제공업체에 관한 LSA 구조화된 데이터를 제공하는 방법을 설명합니다. 특히 LSA와 통합하기 위해 집계기가 구현해야 하는 API 엔드포인트 집합을 문서화합니다.
용어 설명
애그리게이터 (또는 파트너): 서비스를 제공하고 데이터가 LSA에 제공될 수 있는 제공업체를 집계하는 파트너입니다.
서드 파티 제공업체 (또는 등록정보): 이는 개별 소규모 비즈니스 (예: 집계업체와 비즈니스 관계를 맺고 있을 수 있는 비즈니스(예: Joe의 배관) 애그리게이터는 이러한 비즈니스에 관한 정보를 지역 서비스에 제공합니다.
개요
애그리게이터는 피드를 사용하여 제공업체 (비즈니스)에 관한 데이터를 지역 서비스에 제공합니다. 각 피드는 여러 제공업체에 관한 데이터로 구성됩니다. 피드 내에서 단일 제공업체에 관한 데이터는 피드 항목으로 캡슐화됩니다. 각 피드에는 피드의 최신성을 나타내는 피드 타임스탬프도 지정되어 있습니다. 각 피드에는 피드 유형도 지정됩니다. 아래에 설명된 대로 제공업체 프로필 또는 제공업체 리뷰에 관한 데이터일 수 있습니다.
피드 유형
초기 통합의 경우 각 피드는 다음 피드 유형 중 하나일 수 있습니다.
프로필 피드: 이 피드는 제공업체 프로필에 관한 정보를 제공합니다. 각 피드 항목은 특정 제공업체에 관한 프로필 정보를 요약합니다. 여기에는 고유한 비즈니스 ID, 비즈니스 이름, 게재 위치, 제공되는 서비스, 영업시간 등이 포함됩니다. 피드 항목에는 이 비즈니스의 게재 메타데이터 (예: 월별 예산 금액, 광고 상태 등)도 포함됩니다.
리뷰 피드: 이 피드는 제공업체 리뷰에 관한 정보를 제공합니다. 각 피드 항목은 특정 제공업체에 대한 자세한 소비자 리뷰 목록을 캡슐화합니다. 각 소비자 리뷰는 소비자 이름, 평점 (1~5), 리뷰 텍스트, 리뷰 타임스탬프 등으로 구성됩니다.
프로필 피드 및 리뷰 피드의 특정 필드와 그 의미에 대한 자세한 내용
피드 수집
피드 데이터는 JSON으로 직렬화됩니다. 데이터를 제출하기 위해 LSA는 풀 메커니즘만 지원합니다. 푸시 메커니즘을 지원할 계획이 있습니다.
풀 메커니즘
풀 메커니즘에서 애그리게이터는 JSON 객체를 전송하고 수신하는 사전 정의된 REST 엔드포인트(URL) 집합을 지원합니다. 이는 웹 서버에 하나 이상의 파일을 호스팅하는 것과 유사합니다. LSA는 데이터를 가져오기 위해 이러한 URL에 주기적으로 HTTP GET 요청을 발행합니다. 사전 정의된 URL에 대한 자세한 내용은 API 엔드포인트에 관한 다음 섹션을 참고하세요.
푸시 메커니즘
푸시 메커니즘에서 LSA는 집계기가 호출하고 데이터를 제공할 수 있는 엔드포인트를 제공합니다. 의미상으로는 가져오기와 동일하지만, 어그리게이터가 특정 데이터를 지역 서비스에 푸시하려는 경우 유연성을 제공합니다. 프로토콜에 설명된 모든 시맨틱, 규칙 또는 제약 조건은 푸시와 풀에 동일한 방식으로 적용됩니다.
API 엔드포인트
다음 엔드포인트는 애그리게이터에서 지원해야 합니다. 하나는 프로필 피드용이고 하나는 리뷰 피드용입니다.
추천 엔드포인트 경로
엔드포인트에 아래와 같은 버전 정보가 포함되는 것이 좋습니다. v1로 시작합니다.
| 엔드포인트 | 경로 |
|---|---|
| 프로필 피드 | /feeds/{version}/profile |
| 피드 검토 | /feeds/{version}/review |
엔드포인트 매개변수
| Params | 설명 |
|---|---|
maxresults |
페이지에서 요청할 수 있는 피드 항목 수의 한도입니다. |
nextpagetoken |
결과의 다음 페이지를 가져오는 페이지 나누기 토큰입니다. |
엔드포인트 인증
인증은 HTTP 기본 액세스 인증을 사용합니다. 인증을 위한 base64 인코딩된 사용자 이름과 비밀번호입니다. 아래에 예시가 나와 있습니다.
username'승인'(설명 목적으로만 제공)passwordJ9adfdsafc3RfMjpVU1yif5XMw' (설명 목적으로만 제공)
푸시용 SFTP 보관용 계정
Dropbox 경로: partnerupload.google.com:19321
경고: 이 SFTP 드롭박스에 로드된 파일은 24시간 후에 자동으로 삭제됩니다.
엔드포인트 인증
공개 키/비공개 키 쌍 (권장)
- 여기 튜토리얼을 사용하여 키 쌍을 생성합니다.
- LSA에 공개 키를 보내고 인증을 위해 비공개 키를 유지합니다.
- LSA는 공개 키를 사용하여 사용자 이름을 생성하고 어그리게이터에 다시 전송합니다.
비밀번호 인증
- LSA가 사용자 이름과 비밀번호를 생성하여 애그리게이터에 다시 전송합니다.
SFTP 명령어 빠른 참조
로그인합니다. 이 명령어를 사용하여 로그인합니다.
(비공개 키를 사용하지 않는 경우 -i를 생략하세요). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com파일을 복사합니다. 파일을 원격 시스템에 복사합니다.
lls/lcd를 사용하여 로컬 시스템에ls/cd하여 파일을 찾을 수 있습니다. 그런 다음 다음을 통해 파일을 복사합니다.put <path_to_local_file>확인
ls를 사용하여 SFTP 디렉터리의 폴더 및 파일 목록을 확인하고 파일이 원격 시스템에 복사되었는지 확인합니다.
피드 카테고리
앞에서 언급했듯이 각 피드는 파일과 유사하며 여러 피드 항목으로 구성됩니다. 각 피드 항목은 특정 제공업체 (고유한 비즈니스 ID)에 관한 데이터를 캡슐화합니다. 각 피드에는 이 피드의 최신성을 나타내는 타임스탬프도 있습니다. 피드 카테고리는 LSA가 지정된 피드를 해석하는 방법을 지정합니다. 아래에 설명된 대로 피드에는 두 가지 카테고리가 있습니다.
스냅샷 피드에는 특정 타임스탬프의 애그리게이터에 속한 제공업체의 전체 목록이 포함됩니다. 이 스냅샷 피드를 처리한 후에는 다음 시맨틱이 적용됩니다.
피드에 있는 모든 제공업체의 경우 시스템은 LSA 데이터베이스에서 이 제공업체의 데이터를 업데이트합니다 (예: 처음 발견된 경우 새 제공업자를 만들거나 이전 피드에서 제공업자가 처리된 경우 제공업자 데이터를 업데이트).
현재 LSA 데이터베이스에 있지만 피드에 누락된 어그리게이터의 모든 제공업체는 삭제됩니다.
업데이트 (또는 증분) 피드에는 특정 타임스탬프의 일부 제공업체 목록 (애그리게이터 아래)이 포함됩니다. 증분 피드를 처리한 후에는 다음 시맨틱이 적용됩니다.
피드에 있는 모든 제공업체의 경우, 이전 스냅샷 피드에서 제공업체가 생성된 경우 시스템은 LSA 데이터베이스에서 이 제공업체의 데이터를 업데이트합니다. (예: 제공업체를 처음 발견한 경우 작업이 없습니다.)
현재 LSA 데이터베이스에 있지만 피드에 없는 제공업체의 경우 작업이 실행되지 않습니다 (즉, 이 제공업체는 변경되지 않음).
프로필과 리뷰 피드의 의미는 약간 다릅니다. 처리 세부정보는 개별 피드 시맨틱을 참고하세요.
프로필 피드: * 풀 기반 스냅샷 피드 * 푸시 기반 스냅샷 피드 * 푸시 기반 업데이트 피드 리뷰 피드: * 풀 기반 스냅샷 피드 * 푸시 기반 스냅샷 피드
다음의 경우 별도의 프로필 피드가 필요합니다.
예
스냅샷 피드
스냅샷 피드는 전체 제공업체 목록으로 구성됩니다. 예를 들어 집계자가 100개의 제공업체를 LSA에 인그레션하려고 하는 경우 스냅샷 피드에는 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이 있습니다.
피드 업데이트 (증분)
업데이트 피드에는 어그리게이터 아래에 있는 제공업체의 일부 목록이 포함됩니다. 예를 들어 어그리게이터가 이전에 제공된 100개의 제공업체 중 5개만 업데이트하려는 경우 업데이트 피드에는 이러한 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, Pro3이 있습니다.
스냅샷 및 풀의 영향
스냅샷 피드 + 풀 메커니즘에는 다음과 같은 제한사항이 적용됩니다.
- 파트너가 제공업체를 추가 또는 삭제하거나, 프로필 정보를 업데이트하거나, 광고를 일시중지하거나, 예산을 변경하는 데 몇 시간 정도 지연될 수 있습니다. 지연은 풀 요청의 빈도와 직접적인 관련이 있습니다.
- 긴급한 데이터 업데이트의 경우 일회성/임시 풀을 수동으로 지원해야 할 수 있습니다.
증분 및 푸시 지원의 의미
피드 업데이트 + 푸시 메커니즘을 열면 다음과 같은 개선사항이 적용됩니다.
- 파트너는 스냅샷 피드를 푸시 또는 풀로 제공할 수 있습니다. 엔드포인트 (풀)를 유지하지 않으려는 파트너는 대신 푸시를 사용하여 엔드포인트 유지관리 비용을 줄일 수 있습니다. 파트너가 이미 풀에서 스냅샷 피드를 지원하는 경우 풀에서 스냅샷을 계속 제공해도 됩니다.
- 파트너는 증분 업데이트를 사용하여 프로필 변경사항이 있는 일부 제공업체만 업데이트할 수 있습니다. 이렇게 하면 프로필 데이터의 최신 상태가 개선됩니다.
- 스냅샷과 증분, 푸시와 풀을 선택하는 방법에 관해서는 이 섹션에서 권장되는 통합 접근 방식을 참고하세요.
권장 통합 접근 방식
파트너는 푸시 또는 풀을 통해 주기적인 스냅샷 피드를 보유해야 합니다. 이를 통해 LSA는 업데이트 누락 시 롤백 및 시스템 복구와 같은 비상 상황을 처리할 수 있습니다.
- 푸시 메커니즘을 사용하면 파트너는 2시간마다 스냅샷 프로필 피드를 푸시하고 6시간마다 피드를 검토하여 기준 데이터의 최신성을 보장해야 합니다.
- 풀 메커니즘을 사용하면 LSA가 2시간마다 스냅샷 프로필 피드를 가져오고 6시간마다 피드를 검토하여 기준 데이터의 최신성을 보장합니다.
- 파트너는 스냅샷 피드를 전송하기 위해 메커니즘 (푸시 또는 풀) 중 하나만 필요하며 둘 다 필요하지는 않습니다.
원하는 경우 데이터 업데이트 빈도를 개선하려는 파트너는 푸시를 통해 업데이트 피드를 전송할 수 있습니다. LSA는 업데이트 피드를 가져오지 않습니다.
- 업데이트 피드는 다음 스냅샷을 기다리지 않고 마지막 스냅샷 이후 변경된 항목을 전파하는 데 사용됩니다.
- LSA는 제공업체가 두 푸시 사이에 5분 이상의 간격을 두도록 권장합니다.
- 업데이트 피드에서 피드 항목을 적절하게 번들로 묶는 것이 좋습니다. 제공자 5개를 업데이트하는 경우 LSA는 각 피드에 피드 항목이 1개씩 있는 업데이트 피드 5개를 푸시하는 대신 피드 항목이 5개인 업데이트 피드 1개를 푸시하는 것을 선호합니다.
- LSA는 리뷰 피드가 아닌 프로필 피드에 대해서만 증분 피드를 지원합니다.
LSA는 데이터 일관성을 보장하기 위해 메타데이터의 feedTimestampMicros 필드를 따릅니다. 동일한 전문가를 업데이트하는 최신 항목이 수집된 경우 오래된 타임스탬프가 있는 피드 항목은 오래된 항목이 도입되지 않도록 건너뜁니다. 스냅샷 피드와 업데이트 피드 모두에서 feedTimestampMicros를 사용하여 데이터 업데이트 빈도를 올바르게 반영하는 것은 파트너의 책임입니다.
파트너는 Reporting API를 사용하여 제공업체별 리드 및 요금 정보를 가져와야 합니다.