Merchant Product API 總覽

本頁說明如何以程式輔助方式上傳及管理產品。使用 Merchant Products API，您可以在資料來源中插入或更新產品、從帳戶中擷取產品，以及從資料來源中刪除產品。

Merchant Products API 包含兩個資源。

productInputs 可分為主要和補充，取決於是否已上傳至主要資料來源或補充資料來源。每個 product 都會由單一主要 productInput 和任意數量的補充 productInputs 建構而成。

你可以使用 Merchant Products API 建立線上或店面商品目錄，這些產品可顯示在多個購物目的地中。建立 Merchant Center 帳戶、設定第一個資料來源，並準備好透過 API 上傳初始產品組合後，即可使用 productInputs 資源。

雖然商家可以使用檔案上傳產品 (稱為 PrimaryProductDataSource)，但使用 Merchant API 建立和刪除產品有許多優點。這些優點包括回應時間更快，以及能夠即時更新產品，而無需管理大型檔案。透過 API 呼叫所做的產品變更，最多可能需要幾小時才會顯示在購物資料庫中。

必要條件

如果沒有資料來源，請使用 Merchant DataSources API 或 Merchant Center 建立資料來源。

如果您已使用 Merchant Center UI 或 API 建立資料來源，可以使用 Merchant Products API 新增產品。如果你使用 Content API for Shopping 新增產品，請參閱遷移指南，瞭解如何開始使用 Merchant Products API。

請務必遵守「購物廣告」和「免費產品資訊」政策。購物廣告有權執行這些政策，並在發現違反這些政策的內容或行為時採取適當回應。

資源

products 資源可讓您從 Shopping 資料庫擷取產品資訊。

productInput 資源代表您為產品提交的輸入資料。它也提供方法，讓你一次更新或刪除多個產品資訊，或在批次模式中一次更新或刪除多個產品資訊。productInput 資源必須包含下列欄位：

  • channel：產品的管道。
  • offerId：產品的專屬 ID。
  • contentLanguage：產品的雙字母 ISO 639-1 語言代碼。
  • feedLabel：產品的動態饋給標籤。

將產品輸入內容上傳至帳戶

如要將產品輸入內容上傳至帳戶，請使用 accounts.productInputs.insert 方法。您必須傳遞主要或輔助資料來源的專屬 ID。

以下要求範例說明如何使用 accounts.productInputs.insert 方法，將產品輸入內容上傳至商家帳戶。這項要求會設定運送價格和區域，以及自訂屬性 (例如製造日期和尺寸)。

POST https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE}

{
  "name": "{PRODUCT_TITLE}",
  "versionNumber": {VERSION_NUMBER},
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "offerId": "{OFFER_ID}",
  "channel": "ONLINE",
  "attributes": {
    "availability": "in stock",
    "imageLink": "{IMAGE_LINK}",
    "link": "{PRODUCT_LINK}",
    "brand": "{BRAND_NAME}",
    "price": {
      "currencyCode": "{CURRENCY_CODE}",
      "amountMicros": {PRICE}
    },
    "color": "red",
    "productWeight": {
      "value": 320,
      "unit": "g"
    },
    "adult": false,
    "shipping": [
      {
        "country": "GB",
        "price": {
          "amountMicros": {SHIPPING_COST},
          "currencyCode": "{CURRENCY_CODE_SHIPPING}"
        },
        "postalCode": "{SHIPPING_POSTALCODE}",
        "service": "",
        "region": "{SHIPPING_REGION}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}"
      }
    ],
    "gender": "Female"
  },
  "customAttributes": [
    {
      "name": "size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

更改下列內容：

  • {ACCOUNT_ID}：Merchant Center 帳戶的專屬 ID。
  • {DATASOURCE}：資料來源的專屬 ID。格式應為 accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}。
  • {PRODUCT_TITLE}：產品名稱。
  • {VERSION_NUMBER}：產品的版本號碼。選填。
  • {CONTENT_LANGUAGE}：產品的雙字母 ISO 639-1 語言代碼。必填。
  • {FEED_LABEL}：您要銷售產品的地區的 CLDR 區域代碼。如果為 feedLabel 提供的值無效，系統就不會填入 targetCountry 欄位。
  • {OFFER_ID}：產品的專屬 ID。必填。
  • {IMAGE_LINK}：產品圖片在網站上的連結。選填。
  • {PRODUCT_LINK}：網站上產品的連結。選填。
  • {CURRENCY_CODE}：價格的幣別，採用 ISO 4217 標準的三個英文字母組成。選填。
  • {PRICE}：產品價格，以微秒為單位的數字表示。選填。
  • {SHIPPING_COST}：固定運費價格，以數字表示。選填。
  • {SHIPPING_POSTALCODE}：套用運費的郵遞區號範圍。選填。
  • {MAX_HANDLING_TIME}：從收到訂單到出貨之間，最長的處理時間 (以工作天為單位)。選填。
  • {MIN_HANDLING_TIME}：從收到訂單到出貨之間，最短處理時間 (以工作天為單位)。值為 0 表示訂單會在收到訂單當天送達。選填。
  • {MAX_TRANSIT_TIME}：從訂單出貨到送達之間，最長的運送時間 (以工作天為單位)。選填。
  • {MIN_TRANSIT_TIME}：從訂單出貨到送達之間，最短的運送時間 (以工作天為單位)。值為 0 表示訂單會在出貨當天送達。選填。

如果要求執行成功，您會看到下列回應：

{
  "name": "{PRODUCT_NAME}",
  "product": "{PRODUCT_ID}",
  "channel": "ONLINE",
  "offerId": "{OFFER_ID}",
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "versionNumber": "{VERSION_NUMBER}",
  "attributes": {
    "link": "{PRODUCT_LINK}",
    "imageLink": "{IMAGE_LINK}",
    "adult": false,
    "availability": "in stock",
    "brand": "{BRAND_NAME}",
    "color": "red",
    "gender": "Female",
    "price": {
      "amountMicros": "{PRICE}",
      "currencyCode": "{CURRENCY_CODE}"
    },
    "shipping": [
      {
        "price": {
          "amountMicros": "{SHIPPING_COST}",
          "currencyCode": "{CURRENCY_CODE}"
        },
        "country": "{SHIPPING_COUNTRY}",
        "region": "{SHIPPING_REGION}",
        "postalCode": "{SHIPPING_POSTALCODE}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}"
      }
    ],
    "productWeight": {
      "value": 320,
      "unit": "g"
    }
  },
  "customAttributes": [
    {
      "name": "Size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

從帳戶中擷取已處理的產品

如要從帳戶中擷取已處理的產品，請使用 accounts.products.get 方法。插入後，系統可能需要幾分鐘的時間才能顯示已處理的產品。

您可以從 accounts.productInputs.insert 的回應中取得 product 欄位的處理產品資源名稱。

從帳戶中刪除產品輸入內容

如要從帳戶中刪除產品輸入內容，請使用 accounts.productInputs.delete 方法。如要使用 Merchant Products API 刪除產品，你必須傳遞產品所屬主要或補充資料來源的專屬 ID。

列出帳戶中的產品

如要列出帳戶中已處理的產品，請使用 accounts.products.list 方法。