Dịch vụ truy cập MCP Merchant API (Alpha)

Sử dụng Dịch vụ truy cập Giao thức ngữ cảnh mô hình (MCP) của Merchant API để có quyền truy cập được uỷ quyền vào dữ liệu và thông tin chi tiết của bạn trong Merchant Center, từ đó xây dựng trải nghiệm dựa trên tác nhân và quy trình công việc tự động mới.

Tổng quan

Dịch vụ truy cập MCP của Merchant API cung cấp một cầu nối bảo mật, được chuẩn hoá cho các LLM, tác nhân và trợ lý lập trình để xây dựng và điều phối các trải nghiệm mới dựa trên tác nhân và quy trình công việc tự động dựa trên dữ liệu của Merchant Center.

Cụ thể, API này cho phép truy cập có uỷ quyền vào dữ liệu Merchant Center của bạn, cũng như các báo cáo và thông tin chi tiết do Google tạo để thực hiện các thao tác chỉ đọc và ghi có giới hạn nhằm giải quyết các trường hợp sử dụng như:

• Chẩn đoán và khắc phục tình trạng sản phẩm bị từ chối
• Tạo báo cáo hiệu suất và thông tin chi tiết
• Xem xét việc chọn sử dụng tính năng tự động cải thiện
• Tạo và tìm nạp nguồn dữ liệu

Các chế độ kiểm soát quyền truy cập và an toàn

Dịch vụ truy cập MCP của Merchant API được thiết kế chú trọng đến tính bảo mật:

• Xác thực: Việc thực thi công cụ chịu sự điều chỉnh của quy trình xác thực Merchant API tiêu chuẩn, yêu cầu OAuth 2.0 hoặc thông tin đăng nhập tài khoản dịch vụ. Bạn nên sử dụng thông tin xác thực có quyền truy cập hạn chế nhất có thể.
• An toàn khi thực thi: Mặc dù chế độ hiển thị công cụ không bị hạn chế đối với hoạt động khám phá của tác nhân, nhưng việc thực thi công cụ chỉ được giới hạn ở thông tin xác thực API cụ thể của bạn.
• Biện pháp bảo vệ: Các công cụ chỉ được phép thực hiện các thao tác chỉ đọc và các công cụ ghi có rủi ro thấp (ví dụ: tạo nguồn dữ liệu) để đảm bảo an toàn.

Điểm quan trọng cần lưu ý

Dịch vụ truy cập MCP của Merchant API là phiên bản alpha; phạm vi và chức năng của dịch vụ này sẽ được mở rộng và có thể thay đổi.

Trước khi bắt đầu, hãy xem các hạn chế và phương pháp hay nhất sau đây:

Các thay đổi và bản phát hành

Các thay đổi có thể xảy ra mà không cần thông báo trước và sẽ được công bố trong ghi chú phát hành.

Thử nghiệm an toàn

Bạn nên thử nghiệm trước bằng cách sử dụng tài khoản thử nghiệm hoặc tài khoản không hoạt động trước khi sử dụng các công cụ này trong môi trường thực tế.

Hạn mức dùng chung

Dịch vụ truy cập MCP của Merchant API dùng chung nhóm hạn mức với các lệnh gọi Merchant API tiêu chuẩn. Việc chạy tác nhân có thể nhanh chóng làm cạn hạn mức, đặc biệt là khi tìm nạp nguồn dữ liệu. Bạn nên sử dụng tài khoản thử nghiệm để tránh làm gián đoạn dịch vụ chính thức.

Lọc và đảm bảo an toàn cho công cụ

Các tính năng mới, đặc biệt là thao tác ghi, sẽ được bổ sung trong tương lai. Bạn nên định cấu hình rõ ràng ứng dụng của mình để lọc công cụ tích hợp sẵn thay vì hiển thị toàn bộ bộ công cụ.

Tóm tắt các tính năng hiện có

Bạn có thể sử dụng Dịch vụ truy cập MCP của Merchant API để thực hiện các hành động sau theo cách của tác nhân:

• Truy xuất trạng thái chi tiết và bối cảnh báo cáo cho một số sản phẩm cụ thể bằng cách sử dụng tên tài nguyên chính xác.
• Liệt kê và tìm kiếm nhiều sản phẩm.
• Truy vấn các chỉ số hiệu suất, trạng thái sản phẩm và thông tin chi tiết về sản phẩm phổ biến, thông tin chi tiết về giá, mức độ hiển thị cạnh tranh và số liệu phân tích về chương trình tiếp thị liên kết của YouTube Shopping.
• Xác định các vấn đề ở cấp tài khoản ảnh hưởng đến khả năng hiển thị sản phẩm hoặc việc tham gia chương trình.
• Liệt kê, tạo, tìm nạp và kiểm tra trạng thái tải lên của nguồn dữ liệu.
• Liệt kê các lý do tổng hợp khiến sản phẩm bị từ chối trong kho hàng của bạn.
• Xem lại chế độ cài đặt tự động cải thiện cho các mặt hàng, hình ảnh và thông tin vận chuyển.
• Kiểm tra các khu vực đang hoạt động, các yêu cầu chưa được đáp ứng và trạng thái tham gia của các chương trình cụ thể trong Merchant Center.

Bắt đầu

Để kết nối IDE, trợ giúp lập trình hoặc tác nhân với Dịch vụ truy cập MCP của Merchant API, hãy cập nhật chế độ cài đặt ứng dụng MCP (ví dụ: mcp.json hoặc settings.json).

Cấu hình ứng dụng

Thiết lập cấu hình:

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

claude mcp add --transport http merchant-api https://merchantapi.googleapis.com/mcp --scope local \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}"

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_data_sources" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

Các trường hợp sử dụng mẫu

Để minh hoạ cách bạn có thể tận dụng Dịch vụ truy cập MCP của Merchant API để xây dựng trải nghiệm dựa trên tác nhân và quy trình công việc tự động, hãy xem xét các trường hợp sau:

Trường hợp 1: Chẩn đoán và khắc phục tình trạng sản phẩm bị từ chối

Bạn muốn tìm hiểu lý do một số sản phẩm cụ thể không xuất hiện trong kết quả tìm kiếm trên Google.

Câu lệnh của người dùng:

"Tại sao sản phẩm có mã ưu đãi "offer123" của tôi bị từ chối?"

Hành vi của tác nhân với MCP:

1. Tác nhân gọi list_products hoặc get_product_by_name để tìm trạng thái sản phẩm.
2. Máy chủ MCP trả về trạng thái sản phẩm, bao gồm cả danh sách issues (ví dụ: "Định dạng giá không chính xác" hoặc "Thiếu giá trị phí vận chuyển").
3. Nhân viên hỗ trợ sẽ phân tích vấn đề và giải thích nguyên nhân gốc cho bạn, đồng thời đề xuất cách khắc phục (ví dụ: cập nhật thông tin về giá).

Trường hợp 2: Xem xét việc chọn sử dụng tính năng tự động cải thiện

Bạn muốn xác minh xem tính năng tự động cải thiện thông tin vận chuyển có đang hoạt động hay không.

Câu lệnh của người dùng:

"Tôi đã bật tính năng tự động cải thiện thông tin vận chuyển chưa?"

Hành vi của tác nhân với MCP:

1. Tác nhân gọi get_automatic_improvements để truy xuất chế độ cài đặt cấp tài khoản.
2. Máy chủ MCP trả về cấu hình cho biết trạng thái của các điểm cải thiện về hình ảnh, mặt hàng và thông tin vận chuyển.
3. Nhân viên hỗ trợ xác nhận rằng tính năng cải thiện thông tin vận chuyển đang hoạt động hoặc giải thích cách bật tính năng này nếu tính năng này đang tắt.

Trường hợp 3: Tạo báo cáo hiệu suất và thông tin chi tiết

Bạn muốn nhanh chóng kiểm tra hiệu suất gần đây mà không cần di chuyển trong giao diện người dùng của Merchant Center.

Câu lệnh của người dùng:

"Cho tôi xem 5 sản phẩm có hiệu suất cao nhất theo số lượt nhấp vào tuần trước."

Hành vi của tác nhân với MCP:

1. Tác nhân tạo một truy vấn bằng Ngôn ngữ truy vấn của Merchant Center (MCQL) nhắm đến bảng product_performance_view, sắp xếp theo clicks DESC và giới hạn ở 5.
2. Tác nhân gọi report_search bằng truy vấn đã tạo.
3. Máy chủ MCP thực thi truy vấn đối với cơ sở dữ liệu báo cáo trực tiếp và trả về các hàng.
4. Tác nhân sẽ định dạng kết quả thành một bảng Markdown rõ ràng cho bạn.

Trường hợp 4: Tạo và tìm nạp nguồn dữ liệu

Bạn muốn thêm một nguồn dữ liệu mới để tải thông tin cập nhật về sản phẩm lên.

Câu lệnh của người dùng:

"Tạo một nguồn dữ liệu bổ sung có tên là 'price-updates' cho tài khoản người bán của tôi".

Hành vi của tác nhân với MCP:

1. Tác nhân gọi create_data_source bằng các chế độ cài đặt đã chỉ định để đăng ký nguồn cấp dữ liệu mới.
2. Máy chủ MCP tạo nguồn dữ liệu và trả về tên tài nguyên duy nhất của nguồn dữ liệu đó.
3. Tác nhân gọi fetch_data_source để kích hoạt quá trình tải xuống và xử lý tệp liên quan.
4. Tác nhân gọi get_file_upload để theo dõi tiến trình tải lên và xác nhận trạng thái xử lý thành công của các mặt hàng.

Công cụ MCP và nội dung mô tả

Dịch vụ truy cập MCP của Merchant API cung cấp các công cụ sau cho tác nhân của bạn: