Quảng cáo dịch vụ tại địa phương (LSA) để hợp tác với các đơn vị tập hợp nhằm hiển thị trang thông tin của họ (hoặ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 tập hợp các điểm cuối API mà các đơn vị tổng hợp phải triển khai để tích hợp với LSA.
Bảng thuật ngữ
Bên tổng 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à có thể cung cấp dữ liệu của các nhà cung cấp đó cho LSA.
Nhà cung cấp (hoặc trang thông tin) bên thứ ba: Đây là những doanh nghiệp nhỏ riêng lẻ (ví dụ: Joe’s plumbing) có thể có mối quan hệ kinh doanh với các đơn vị tập hợp. Các đơn vị tập hợp cung cấp thông tin về những doanh nghiệp này cho Dịch vụ địa phương.
Tổng quan
Các đơn vị tập 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 bao gồm 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ằng một mục trong nguồn cấp dữ liệu. Mỗi nguồn cấp dữ liệu cũng chỉ định một dấu thời gian của nguồn cấp dữ liệu cho biết độ 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ơ nhà cung cấp hoặc bài đánh giá nhà cung cấp như mô tả bên dưới.
Các loại nguồn cấp dữ liệu
Đối với lần tích hợp ban đầu, mỗi nguồn cấp dữ liệu có thể là một trong các 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ơ của nhà cung cấp. Mỗi mục trong nguồn cấp dữ liệu sẽ đó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ã nhận dạng doanh nghiệp riêng biệ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 trong 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 bài đánh giá: Nguồn cấp dữ liệu này cung cấp thông tin về bài đánh giá nhà cung cấp. Mỗi mục trong nguồn cấp dữ liệu sẽ đó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 tiêu dùng, điểm xếp hạng (1 – 5), nội dung bài đánh giá, dấu thời gian của bài đánh giá, v.v.
Thông tin chi tiết hơn về các trường cụ thể và ngữ nghĩa của các trường đó trong Nguồn cấp dữ liệu hồ sơ và Nguồn cấp dữ liệu bài đánh giá.
Truyền dẫn nguồn cấp dữ liệu
Dữ liệu 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ó kế hoạch hỗ trợ cơ chế truyền dữ liệu trong tương lai.
Cơ chế kéo
Trong cơ chế kéo, các đơn vị tổng hợp hỗ trợ một tập hợp các điểm cuối REST được xác định trước (URL) để 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 xác định trước trong phần tiếp theo về điểm cuối API.
Cơ chế đẩy
Trong cơ chế truyền dữ liệu, LSA sẽ cung cấp một điểm cuối để các đơn vị tổng hợp gọi và cung cấp dữ liệu. Về mặt ngữ nghĩa, điều này tương tự như thao tác kéo, nhưng mang lại sự linh hoạt trong trường hợp các đơn vị 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 đều áp dụng cho cả thao tác đẩy và kéo theo cùng một cách.
Điểm cuối API
Các đơn vị tập hợp phải hỗ trợ những đ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 bài đánh giá.
Đường dẫn điểm cuối được đề xuất
Bạn nên thêm thông tin phiên bản vào các điểm cuối, chẳng hạn như bên dưới. Chúng ta bắt đầu với 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 |
Tham số điểm cuối
| Tham số | Mô tả |
|---|---|
maxresults |
Đây là giới hạn về số lượng mục trong nguồn cấp dữ liệu có thể được yêu cầu trong một trang. |
nextpagetoken |
Mã thông báo phân trang để nhận trang kết quả tiếp theo |
Xác thực thiết bị đầu cuối
Xác thực sử dụng cơ chế xác thực truy cập cơ bản qua 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" (chỉ mang tính minh hoạ)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (chỉ mang tính minh hoạ)
Tài khoản đăng SFTP cho Push
Đường dẫn Dropbox: partnerupload.google.com:19321
CẢNH BÁO: Các tệp được tải vào hộp thả SFTP này sẽ tự động bị xoá sau 24 giờ.
Xác thực thiết bị đầu cuối
Cặp khoá công khai/riêng tư (nên dùng)
- Hãy tham khảo hướng dẫn tại đây để tạo cặp khoá.
- Gửi khoá công khai cho LSA và giữ lại khoá riêng tư để xác thực
- LSA 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 bằng mật khẩu
- LSA sẽ tạo tên người dùng và mật khẩu rồi gửi lại cho đơn vị tổng hợp
Thông tin tham khảo nhanh về lệnh SFTP
Đăng nhập. Sử dụng lệnh này để đăng nhập. (Bỏ -i
nếu bạn không dùng khoá 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ể dùng
lls/lcdđểls/cdvào hệ thống cục bộ để tìm tệp. Sau đó, sao chép tệp thông 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, đồng thời xác minh rằng tệp của bạn đã được sao chép vào 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 trong nguồn cấp dữ liệu. Mỗi mục trong 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 cho biết độ 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ó 2 danh mục nguồn cấp dữ liệu như mô tả bên dưới.
Nguồn cấp dữ liệu thông tin tổng quan chứa danh sách đầy đủ các nhà cung cấp (thuộc một đơn vị tập 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, các ngữ nghĩa sau sẽ được áp dụng:
Đối với mọi nhà cung cấp 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 một nhà cung cấp mới nếu gặp phải lần đầu tiên 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 một nguồn cấp dữ liệu trước đó).
Đối với bất kỳ nhà cung cấp nào thuộc đơn vị tập hợp hiện có trong cơ sở dữ liệu LSA nhưng không có trong nguồn cấp dữ liệu, nhà cung cấp đó sẽ bị xoá.
Nguồn cấp dữ liệu cập nhật (hoặc gia tăng) chứa danh sách một phần các nhà cung cấp (trong một trình tổng hợp) tại một dấu thời gian cụ thể. Sau khi xử lý một nguồn cấp dữ liệu gia tăng, các ngữ nghĩa sau đây sẽ được áp dụng:
Đối với mọi nhà cung cấp 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 ảnh chụp nhanh trước đó. (ví dụ: nếu một nhà cung cấp được gặp lần đầu tiên, thì đó sẽ là một thao tác không có hiệu lực)
Đối với bất kỳ nhà cung cấp nào hiện có trong cơ sở dữ liệu quảng cáo tìm kiếm tại địa phương nhưng không có trong nguồn cấp dữ liệu, đây là một thao tác không có tác dụng (tức là nhà cung cấp này sẽ không thay đổi).
Ngữ nghĩa cho nguồn cấp dữ liệu trang doanh nghiệp so với nguồn cấp dữ liệu bài đánh giá có sự khác biệt nhỏ. Hãy xem ngữ nghĩa của từng nguồn cấp dữ liệu để biết thông tin chi tiết về quy trình xử lý.
Nguồn cấp dữ liệu hồ sơ: * Nguồn cấp dữ liệu ảnh chụp nhanh dựa trên thao tác kéo * Nguồn cấp dữ liệu ảnh chụp nhanh dựa trên thao tác đẩy * Nguồn cấp dữ liệu cập nhật dựa trên thao tác đẩy Nguồn cấp dữ liệu bài đánh giá: * Nguồn cấp dữ liệu ảnh chụp nhanh dựa trên thao tác kéo * Nguồn cấp dữ liệu ảnh chụp nhanh dựa trên thao tác đẩy
Bạn phải có nguồn cấp dữ liệu hồ sơ riêng cho:
Những nhà cung cấp được coi là đủ điều kiện nhận huy hiệu Được Google đảm bảo hoặc Google đã kiểm tra.
Những nhà cung cấp không đủ điều kiện nhận huy hiệu.
Ví dụ
Nguồn cấp dữ liệu ảnh chụp nhanh
Hãy nhớ rằng nguồn cấp dữ liệu ảnh chụp nhanh sẽ bao gồm danh sách đầy đủ các nhà cung cấp. Ví dụ: nếu một đơn vị tổng hợp muốn 100 nhà cung cấp được nhậ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 của cả 100 nhà cung cấp.
Cách hoạt động
Dưới đây là một ví dụ đơn giản minh hoạ 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
- Snapshot 2 có Pro 1, Pro 3
Sau khi xử lý Snapshot 1, cơ sở dữ liệu LSA sẽ có Pro 1 và Pro 2. Trong quá trình xử lý Snapshot 2, LSA sẽ cập nhật Pro 1, tạo Pro 3 và xoá Pro 2. Tức là sau khi xử lý Ảnh chụp nhanh 2, cơ sở dữ liệu LSA sẽ có Pro 1 và Pro 3.
Cập nhật nguồn cấp dữ liệu (tăng dần)
Hãy nhớ rằng nguồn cấp dữ liệu cập nhật chứa một danh sách một phần các nhà cung cấp trong một trang web 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ố 100 nhà cung cấp mà đơn vị này đã cung cấp trước đó, 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 của 5 nhà cung cấp này.
Cách hoạt động
Dưới đây là một ví dụ đơn giản minh hoạ cách hoạt động của danh mục nội dung cập nhật "nguồn cấp dữ liệu hồ sơ".
- Bản cập nhật 1: Pro 1, Pro 2
- Nội dung 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. Xin lưu ý rằng Pro 2 không bị ảnh hưởng. Tức 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.
Hệ quả của tính năng Snapshot và Pull
Cơ chế nguồn cấp dữ liệu ảnh chụp nhanh + kéo ngụ ý các quy tắc hạn chế sau:
- Các đối tác có thể mất vài giờ để thêm hoặc xoá 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. Độ trễ liên quan trực tiếp đến tần suất của các yêu cầu kéo.
- Đối với các bản 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/đặc biệt.
Ý nghĩa của tính năng hỗ trợ gia tăng và thông báo đẩy
Cơ chế mở update feeds + push (cập nhật nguồn cấp dữ liệu + đẩy) mang lại những điểm cải tiến sau:
- Đối tác có thể phân phối nguồn cấp dữ liệu thông tin tóm tắt theo phương thức truyền dữ liệu hoặc truy xuất dữ liệu. Đối với những đối tác không muốn duy trì điểm cuối (để kéo), họ có thể sử dụng tính năng đẩy để giảm chi phí duy trì điểm cuối. Đối tác đã hỗ trợ nguồn cấp dữ liệu ảnh chụp nhanh trong chế độ kéo có thể tiếp tục phân phối ảnh chụp nhanh ở chế độ kéo.
- Đối tác có thể sử dụng các bản cập nhật gia tăng để chỉ cập nhật một nhóm nhỏ nhà cung cấp có thay đổi về hồ sơ. Điều 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 gia số, đẩy so với kéo, hãy xem phần này để biết phương pháp tích hợp được đề 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ỳ, cho dù là thông qua phương thức truyền dữ liệu hay truy xuất dữ liệu. Điều này cho phép LSA xử lý các trường hợp khẩn cấp như khôi phục về phiên bản trước và khôi phục hệ thống trong trường hợp bỏ lỡ các bản cập nhật.
- Với cơ chế truyền dữ liệu, các đối tác nên truyền nguồn cấp dữ liệu hồ sơ nhanh mỗi 2 giờ và nguồn cấp dữ liệu đánh giá mỗi 6 giờ để đảm bảo dữ liệu cơ sở luôn mới.
- Với cơ chế kéo, LSA sẽ kéo nguồn cấp dữ liệu hồ sơ chụp nhanh 2 giờ một lần và nguồn cấp dữ liệu đánh giá 6 giờ một lần để đảm bảo dữ liệu cơ sở luôn mới.
- Đố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 ảnh chụp 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 tính năng đẩ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 tải các mặt hàng đã thay đổi kể từ ảnh chụp nhanh gần đây 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 lớn hơn 5 phút giữa hai lần đẩy.
- Bạn nên nhóm các feeditem một cách hợp lý trong một nguồn cấp dữ liệu cập nhật. Để cập nhật 5 nhà cung cấp, LSA ưu tiên nhà cung cấp gửi 1 nguồn cấp dữ liệu cập nhật có 5 feeditem thay vì gửi 5 nguồn cấp dữ liệu cập nhật có 1 feeditem trong mỗi nguồn cấp dữ liệu.
- LSA chỉ hỗ trợ nguồn cấp dữ liệu gia tăng cho nguồn cấp dữ liệu hồ sơ, chứ không hỗ trợ nguồn cấp dữ liệu bài đánh giá.
LSA sẽ tuân thủ trường feedTimestampMicros trong siêu dữ liệu để đảm bảo tính nhất quán của dữ liệu. Mục nguồn cấp dữ liệu có dấu thời gian cũ hơn sẽ bị bỏ qua để tránh tình trạng cũ nếu một mục mới hơn cập nhật cùng một sản phẩm đã được tiếp nhận. Đối tác có trách nhiệm phản ánh chính xác mứ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 nhanh và nguồn cấp dữ liệu cập nhật.
Đối tác nên sử dụng Reporting API để nhận thông tin về khách hàng tiềm năng và phí theo từng nhà cung cấp.