Quảng cáo dịch vụ địa phương (LSA) hợp tác với các đơn vị tập hợp để đăng trang thông tin của họ (hoặc các nhà cung cấp) trên Google.com. Trong hướng dẫn này, chúng tôi mô tả cách các đơn vị tập hợp có thể cung cấp dữ liệu có cấu trúc LSA về nhà cung cấp của họ. Cụ thể, chúng tôi ghi lại bộ tập hợp điểm cuối API phải triển khai để tích hợp với LSA.
Bảng thuật ngữ
Đơn vị tập hợp (hoặc đối tác): Đây là những đối tác tổng hợp các nhà cung cấp mà họ cung cấp dịch vụ và dữ liệu có thể được cung cấp cho LSA.
Nhà cung cấp bên thứ ba (hoặc trang thông tin): Đây là những doanh nghiệp nhỏ riêng lẻ (ví dụ: Joe, thợ sửa ống nước), người có thể có mối quan hệ kinh doanh với các đơn vị tập hợp. Trang web tổng hợp cung cấp thông tin về Dịch vụ địa phương về các doanh nghiệp này.
Tổng quan
Trang web tổng hợp sẽ cung cấp dữ liệu về nhà cung cấp (doanh nghiệp) của họ cho Dịch vụ địa phương bằng cách sử dụng nguồn cấp dữ liệu. Mỗi nguồn cấp dữ liệu chứa dữ liệu về nhiều nhà cung cấp. Trong một nguồn cấp dữ liệu, dữ liệu về một nhà cung cấp duy nhất được đóng gói bởi một mục nguồn cấp dữ liệu. Mỗi nguồn cấp dữ liệu cũng chỉ định dấu thời gian của nguồn cấp dữ liệu biểu thị độ mới của nguồn cấp dữ liệu. Mỗi nguồn cấp dữ liệu cũng chỉ định một loại nguồn cấp dữ liệu: đây có thể là dữ liệu về hồ sơ của nhà cung cấp hoặc bài đánh giá của nhà cung cấp như được mô tả bên dưới.
Loại nguồn cấp dữ liệu
Trong quy trình tích hợp ban đầu, mỗi nguồn cấp dữ liệu có thể thuộc một trong những loại nguồn cấp dữ liệu sau:
Nguồn cấp dữ liệu hồ sơ: Nguồn cấp dữ liệu này cung cấp thông tin về hồ sơ nhà cung cấp. Mỗi mục nguồn cấp dữ liệu đóng gói thông tin hồ sơ về một nhà cung cấp cụ thể. Thông tin này bao gồm một mã doanh nghiệp duy nhất, tên doanh nghiệp, vị trí phân phát, dịch vụ được cung cấp, giờ hoạt động, v.v. Mục nguồn cấp dữ liệu cũng chứa siêu dữ liệu phân phát cho doanh nghiệp này (ví dụ: số tiền ngân sách hằng tháng, trạng thái quảng cáo, v.v.).
Nguồn cấp dữ liệu đánh giá: Nguồn cấp dữ liệu này cung cấp thông tin về các bài đánh giá của nhà cung cấp. Mỗi mục nguồn cấp dữ liệu đóng gói một danh sách các bài đánh giá chi tiết của người tiêu dùng về một nhà cung cấp cụ thể. Mỗi bài đánh giá của người tiêu dùng bao gồm tên người dùng, điểm xếp hạng (1 – 5), văn bản đánh giá, dấu thời gian đánh giá, v.v.
Bạn có thể xem thêm thông tin chi tiết về các trường cụ thể và ngữ nghĩa trong Nguồn cấp dữ liệu hồ sơ và Nguồn cấp dữ liệu đánh giá.
Nhập nguồn cấp dữ liệu
Dữ liệu của nguồn cấp dữ liệu được chuyển đổi tuần tự dưới dạng JSON. Để gửi dữ liệu, LSA sẽ chỉ hỗ trợ cơ chế kéo. Chúng tôi cũng dự định hỗ trợ một cơ chế đẩy trong tương lai.
Cơ chế kéo
Trong cơ chế kéo, trang web tổng hợp hỗ trợ một tập hợp các điểm cuối REST (URL) được xác định trước sẽ gửi và nhận các đối tượng JSON. Điều này tương tự như việc lưu trữ một hoặc nhiều tệp trên máy chủ web. LSA sẽ định kỳ gửi yêu cầu HTTP GET đến các URL này để tìm nạp dữ liệu. Bạn có thể xem thông tin chi tiết về các URL được xác định trước trong phần tiếp theo về các điểm cuối API.
Cơ chế đẩy
Trong cơ chế đẩy, LSA sẽ cung cấp một điểm cuối để các trình tổng hợp gọi và cung cấp dữ liệu. Về mặt ngữ nghĩa, đây giống như một chế độ phân phối lấy dữ liệu, nhưng cung cấp tính linh hoạt trong trường hợp các trang web tổng hợp muốn đẩy dữ liệu cụ thể đến Dịch vụ địa phương. Tất cả ngữ nghĩa, quy tắc hoặc ràng buộc được mô tả trong giao thức áp dụng cho cả cách đẩy và kéo theo cùng một cách.
Điểm cuối API
Các đơn vị tập hợp nên hỗ trợ các điểm cuối sau: một cho nguồn cấp dữ liệu hồ sơ và một cho nguồn cấp dữ liệu đánh giá.
Đường dẫn điểm cuối đề xuất
Bạn nên sử dụng những điểm cuối như thông tin phiên bản như bên dưới. Chúng ta bắt đầu
bằng v1.
| Điểm cuối | Đường dẫn |
|---|---|
| Nguồn cấp dữ liệu hồ sơ | /feeds/{version}/profile |
| Xem xét nguồn cấp dữ liệu | /feeds/{version}/review |
Thông số điểm cuối
| Thông số | Mô tả |
|---|---|
maxresults |
Đây là giới hạn về số lượng mục nguồn cấp dữ liệu có thể được yêu cầu trong một trang. |
nextpagetoken |
Mã phân trang để nhận trang kết quả tiếp theo |
Xác thực điểm cuối
Xác thực sử dụng xác thực truy cập cơ bản HTTP: tên người dùng và mật khẩu được mã hoá base64 để xác thực. Dưới đây là ví dụ.
username"Uỷ quyền" (để minh hoạ)passwordJ9adfdstvOS3RfMjpVU1yif5XMw” (nhằm mục đích minh họa)
Tài khoản đăng SFTP
Đường dẫn trong Dropbox: partnerupload.google.com:19321
CẢNH BÁO: Các tệp được tải vào hộp thả xuống SFTP này sẽ tự động bị xóa sau 24 giờ.
Xác thực điểm cuối
Cặp khóa công khai/riêng tư (khuyên dùng)
- Sử dụng hướng dẫn tại đây để tạo các cặp khóa.
- Gửi khoá công khai LSA và giữ khoá riêng tư để xác thực
- LSA sẽ sử dụng khoá công khai để tạo tên người dùng và gửi lại cho trình tổng hợp
Xác thực mật khẩu
- LSA sẽ tạo tên người dùng và mật khẩu, sau đó gửi lại cho trang web tổng hợp
Tài liệu tham khảo nhanh về lệnh SFTP
Đăng nhập. Sử dụng lệnh này để đăng nhập. (Bỏ qua -i
nếu bạn không sử dụng khóa riêng tư. sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comSao chép tệp. Sao chép tệp vào hệ thống từ xa. Bạn có thể sử dụng
lls/lcdđểls/cdvào hệ thống cục bộ để tìm tệp. Sau đó, hãy sao chép tệp qua:put <path_to_local_file>Xác minh. Sử dụng
lsđể xem danh sách các thư mục và tệp trong thư mục SFTP và xác minh rằng tệp của bạn đã được sao chép sang hệ thống từ xa
Danh mục nguồn cấp dữ liệu
Như đã lưu ý trước đó, mỗi nguồn cấp dữ liệu tương tự như một tệp và bao gồm một số mục nguồn cấp dữ liệu. Mỗi mục nguồn cấp dữ liệu đóng gói dữ liệu về một nhà cung cấp cụ thể (mã doanh nghiệp duy nhất). Mỗi nguồn cấp dữ liệu cũng có một dấu thời gian biểu thị độ mới của nguồn cấp dữ liệu này. Danh mục nguồn cấp dữ liệu chỉ định cách LSA diễn giải một nguồn cấp dữ liệu nhất định. Có hai loại nguồn cấp dữ liệu như mô tả dưới đây.
Nguồn cấp dữ liệu ảnh chụp nhanh chứa danh sách đầy đủ các nhà cung cấp (bên dưới trang web tổng hợp) tại một dấu thời gian cụ thể. Sau khi xử lý nguồn cấp dữ liệu ảnh chụp nhanh này, ngữ nghĩa sau đây sẽ được áp dụng:
Đối với bất kỳ nhà cung cấp nào có trong nguồn cấp dữ liệu, hệ thống sẽ cập nhật dữ liệu cho nhà cung cấp này trong cơ sở dữ liệu LSA (ví dụ: tạo nhà cung cấp mới nếu gặp lần đầu hoặc cập nhật dữ liệu của nhà cung cấp nếu nhà cung cấp được xử lý trong nguồn cấp dữ liệu trước đó).
Đối với bất kỳ nhà cung cấp nào trong trình tổng hợp hiện có trong cơ sở dữ liệu LSA, nhưng bị thiếu trong nguồn cấp dữ liệu, thì nhà cung cấp đó sẽ bị xóa.
Nguồn cấp dữ liệu cập nhật (hoặc Nguồn cấp dữ liệu tăng dần) chứa một phần danh sách nhà cung cấp (dưới dạng trình tổng hợp) tại một dấu thời gian cụ thể. Sau khi xử lý nguồn cấp dữ liệu tăng dần, các ngữ nghĩa sau sẽ áp dụng:
Đối với bất kỳ nhà cung cấp nào có trong nguồn cấp dữ liệu, hệ thống sẽ cập nhật dữ liệu cho nhà cung cấp này trong cơ sở dữ liệu LSA nếu nhà cung cấp được tạo trong nguồn cấp dữ liệu tổng quan nhanh trước đó. (ví dụ: nếu nhà cung cấp gặp lần đầu, thì đó sẽ là không hoạt động)
Đối với bất kỳ nhà cung cấp nào hiện có trong cơ sở dữ liệu LSA, nhưng thiếu nguồn cấp dữ liệu, thì thao tác này không hoạt động (tức là sẽ không có thay đổi nào đối với nhà cung cấp này).
Ngữ nghĩa cho nguồn cấp dữ liệu hồ sơ so với bài đánh giá có chút khác biệt. Xem ngữ nghĩa của từng nguồn cấp dữ liệu để biết thông tin chi tiết về quá trình xử lý.
Trang danh sách video
Bắt buộc phải có nguồn cấp dữ liệu hồ sơ riêng cho:
Các nhà cung cấp được coi là đủ điều kiện để nhận huy hiệu Được Google đảm bảo hoặc Được Google kiểm tra.
Những nhà cung cấp không đủ điều kiện để nhận huy hiệu.
Ví dụ
Trang Tổng quan
Xin lưu ý rằng nguồn cấp dữ liệu tổng quan nhanh sẽ có danh sách đầy đủ các nhà cung cấp. Ví dụ: nếu một đơn vị tổng hợp muốn nhập 100 nhà cung cấp vào LSA, thì nguồn cấp dữ liệu ảnh chụp nhanh phải chứa trạng thái mới nhất cho tất cả 100 nhà cung cấp.
Cách hoạt động
Dưới đây là một ví dụ đơn giản minh họa cách hoạt động của danh mục ảnh chụp nhanh của nguồn cấp dữ liệu hồ sơ.
- Ảnh chụp nhanh 1 có Pro 1, Pro 2
- Ảnh chụp nhanh 2 có Pro 1, Pro 3
Sau khi xử lý Ảnh chụp nhanh 1, cơ sở dữ liệu LSA sẽ có Pro 1 và Pro 2. Trong quá trình xử lý Ảnh chụp nhanh 2, LSA sẽ cập nhật Pro 1, tạo Pro 3 và Delete Pro 2. Nghĩa là, sau khi xử lý Ảnh chụp nhanh 2, cơ sở dữ liệu LSA sẽ có Pro 1 và Pro 3.
Nguồn cấp dữ liệu cập nhật (Tăng dần)
Xin lưu ý rằng nguồn cấp dữ liệu cập nhật chứa danh sách một phần các nhà cung cấp trong một trình tổng hợp. Ví dụ: nếu một đơn vị tập hợp chỉ muốn cập nhật 5 trong số 50 nhà cung cấp trước đó được cung cấp, thì nguồn cấp dữ liệu cập nhật chỉ cần chứa trạng thái mới nhất cho 5 nhà cung cấp này.
Cách hoạt động
Dưới đây là một ví dụ đơn giản minh họa cách hoạt động của danh mục cập nhật của “nguồn cấp dữ liệu hồ sơ”.
- Bản cập nhật 1: Pro 1, Pro 2
- Bản cập nhật 2: Pro 1, Pro 3
Sau khi xử lý Bản cập nhật 1, cơ sở dữ liệu LSA sẽ có Pro 1 và Pro 2. Trong quá trình xử lý Bản cập nhật 2, LSA sẽ cập nhật Pro 1 và tạo Pro 3. Lưu ý rằng Pro 2 là dữ liệu chưa được chỉnh sửa. Nghĩa là, sau khi xử lý Bản cập nhật 2, cơ sở dữ liệu LSA sẽ có Pro1, Pro2 và Pro 3.
Ngụ ý về tính năng Tổng quan nhanh và kéo
Cơ chế nguồn cấp dữ liệu ảnh chụp nhanh + kéo ngụ ý các hạn chế sau:
- Việc thêm hoặc xóa nhà cung cấp, cập nhật thông tin hồ sơ, tạm dừng quảng cáo hoặc thay đổi ngân sách có thể mất vài giờ. Độ trễ có liên quan trực tiếp đến tần suất của các yêu cầu lấy dữ liệu.
- Để cập nhật dữ liệu khẩn cấp, chúng tôi có thể cần hỗ trợ thủ công một lần/lấy dữ liệu đặc biệt.
Ngụ ý về việc hỗ trợ tăng dần và đẩy
Việc mở cơ chế cập nhật nguồn cấp dữ liệu + thông báo đẩy ngụ ý những điểm cải tiến sau đây:
- Đối tác có thể phân phối nguồn cấp dữ liệu tổng quan nhanh bằng cách nhấn hoặc kéo. Những đối tác muốn không duy trì điểm cuối (lấy dữ liệu) có thể sử dụng thao tác đẩy để giảm chi phí bảo trì điểm cuối. Đối tác đã hỗ trợ nguồn cấp dữ liệu ảnh chụp nhanh trong tính năng kéo. Bạn có thể tiếp tục phân phối ảnh chụp nhanh khi kéo.
- Đối tác có thể sử dụng các mô hình tăng dần để chỉ cập nhật một tập hợp con các nhà cung cấp có thay đổi về hồ sơ. Thao tác này giúp cải thiện độ mới của dữ liệu hồ sơ.
- Về cách chọn ảnh chụp nhanh so với mức độ gia tăng, hãy nhấn và kéo, hãy xem phần này để biết phương pháp tích hợp đề xuất.
Phương pháp tích hợp được đề xuất
Đối tác phải có nguồn cấp dữ liệu ảnh chụp nhanh định kỳ, bất kể là qua chế độ đẩy hay kéo. Việc này cho phép LSA xử lý các trường hợp khẩn cấp như khôi phục và khôi phục hệ thống trong trường hợp thiếu bản cập nhật.
- Với cơ chế đẩy, các đối tác nên đẩy nguồn cấp dữ liệu hồ sơ ảnh chụp nhanh 2 giờ một lần và xem xét nguồn cấp dữ liệu mỗi 6 giờ để đảm bảo độ mới của dữ liệu cơ sở.
- Với cơ chế lấy dữ liệu, LSA sẽ lấy nguồn cấp dữ liệu hồ sơ ảnh chụp nhanh 2 giờ một lần và xem xét nguồn cấp dữ liệu mỗi 6 giờ để đảm bảo độ mới của dữ liệu cơ sở.
- Đối tác chỉ cần một trong các cơ chế (đẩy hoặc kéo), nhưng không cần cả hai, để phân phối nguồn cấp dữ liệu tổng quan nhanh.
Nếu muốn cải thiện độ mới của dữ liệu, các đối tác có thể gửi nguồn cấp dữ liệu cập nhật thông qua phương thức đẩy. LSA sẽ không lấy nguồn cấp dữ liệu cập nhật.
- Nguồn cấp dữ liệu cập nhật được dùng để truyền các mục đã thay đổi kể từ ảnh chụp nhanh gần nhất mà không cần chờ ảnh chụp nhanh tiếp theo.
- LSA khuyến nghị các nhà cung cấp nên có khoảng thời gian hơn 5 phút giữa hai lần gửi.
- Bạn nên nhóm các mục nguồn cấp dữ liệu một cách hợp lý trong nguồn cấp dữ liệu cập nhật. Để cập nhật 5 nhà cung cấp, LSA muốn các nhà cung cấp đẩy 1 nguồn cấp dữ liệu cập nhật có 5 mục nguồn cấp dữ liệu thay vì đẩy 5 nguồn cấp dữ liệu cập nhật, trong đó mỗi mục nguồn cấp dữ liệu có 1 mục nguồn cấp dữ liệu.
- LSA chỉ hỗ trợ nguồn cấp dữ liệu tăng dần cho nguồn cấp dữ liệu hồ sơ, chứ không hỗ trợ nguồn cấp dữ liệu đánh giá.
LSA sẽ tuân theo trường feedTimestampMicros trong siêu dữ liệu để đảm bảo tính nhất quán của dữ liệu. Hệ thống sẽ bỏ qua một mục nguồn cấp dữ liệu có dấu thời gian cũ hơn để tránh lỗi cũ nếu một mục mới hơn cập nhật cùng một chuyên nghiệp đã được nhập. Đối tác có trách nhiệm phản ánh chính xác độ mới của dữ liệu bằng cách sử dụng feedTimestampMicros trong cả nguồn cấp dữ liệu tổng quan nhanh và nguồn cấp dữ liệu cập nhật.
Đối tác nên sử dụng API Báo cáo để nhận thông tin về khách hàng tiềm năng và các khoản phí cho mỗi nhà cung cấp.