이 페이지에서는 프로그래매틱 방식으로 제품을 업로드하고 관리하는 방법을 설명합니다. Merchant Products API를 사용하면 데이터 소스에 제품을 삽입하거나 업데이트하고, 계정에서 제품을 검색하고, 데이터 소스에서 제품을 삭제할 수 있습니다.
Merchant Products API에는 두 가지 리소스가 포함되어 있습니다.
productInputs는 제품의 입력 부분을 나타냅니다.products는 입력 부품으로 구성된 처리된 제품을 나타냅니다.
productInputs는 기본 데이터 소스 또는 보조 데이터 소스에 업로드되었는지에 따라 기본 또는 보조일 수 있습니다.
각 product는 단일 기본 productInput와 임의 개수의 보조 productInputs로 구성됩니다.
Merchant Products API를 사용하여 온라인 또는 오프라인 매장 카탈로그를 만들 수 있습니다. 이러한 카탈로그는 여러 쇼핑 대상 유형에 표시될 수 있는 제품입니다.
판매자 센터 계정을 만들고 첫 번째 데이터 소스를 설정했으며 API를 통해 초기 제품 세트를 업로드할 준비가 되면 productInputs 리소스를 사용할 수 있습니다.
판매자는 PrimaryProductDataSource라는 파일을 사용하여 제품을 업로드할 수 있지만 Merchant API를 사용하여 제품을 생성하고 삭제하면 여러 가지 이점이 있습니다. 이러한 이점에는 더 빠른 응답 시간과 대용량 파일을 관리할 필요 없이 실시간으로 제품을 업데이트할 수 있는 기능이 포함됩니다. API 호출로 이루어진 제품 변경사항이 쇼핑 데이터베이스에 표시되기까지 최대 몇 시간이 걸릴 수 있습니다.
기본 요건
데이터 소스가 없는 경우 판매자 데이터 소스 API 또는 판매자 센터를 사용하여 데이터 소스를 만드세요.
판매자 센터 UI 또는 API를 사용하여 만든 데이터 소스가 이미 있는 경우 Merchant Products API를 사용하여 제품을 추가할 수 있습니다. Content API for Shopping을 사용하여 제품을 추가하는 경우 이전 가이드에서 Merchant Products API를 시작하는 방법을 알아보세요.
쇼핑 광고 및 무료 등록정보 정책을 준수할 책임은 판매자에게 있습니다. 쇼핑 광고는 이러한 정책을 시행하고 이러한 정책을 위반하는 콘텐츠나 행동을 발견할 경우 적절하게 대응할 권리를 보유합니다.
리소스
products 리소스를 사용하면 쇼핑 데이터베이스에서 제품 정보를 검색할 수 있습니다.
productInput 리소스는 제품에 대해 제출하는 입력 데이터를 나타냅니다. 또한 일괄 모드에서 제품 정보를 한 번에 하나씩 또는 여러 개 업데이트하거나 삭제할 수 있는 메서드도 제공합니다. productInput 리소스에는 다음 필드가 있어야 합니다.
channel: 제품의 채널입니다.offerId: 제품의 고유 식별자입니다.contentLanguage: 제품의 ISO 639-1 언어 코드(두 글자)입니다.feedLabel: 제품을 분류하고 식별할 수 있는 라벨입니다. 허용되는 최대 문자 수는 20자(영문 기준)이며 지원되는 문자는A-Z,0-9, 하이픈, 밑줄입니다. 피드 라벨에 공백을 포함해서는 안 됩니다. 자세한 내용은 피드 라벨 사용을 참고하세요.
계정에 제품 입력 업로드
제품 입력을 계정에 업로드하려면 accounts.productInputs.insert 메서드를 사용합니다. 기본 또는 보조 데이터 소스의 고유 식별자를 전달해야 합니다.
다음 샘플 요청은 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}: 판매자 센터 계정의 고유 식별자입니다.
- {DATASOURCE}: 데이터 소스의 고유 식별자입니다.
accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID} 형식이어야 합니다. - {PRODUCT_TITLE}: 제품의 이름입니다.
- {VERSION_NUMBER}: 제품의 버전 번호입니다. 선택사항입니다.
- {CONTENT_LANGUAGE}: 제품의 ISO 639-1 언어 코드(두 글자)입니다. 필수 항목입니다.
- {FEED_LABEL}: 제품을 분류하고 식별할 수 있는 라벨입니다. 허용되는 최대 문자 수는 20자(영문 기준)이며 지원되는 문자는
A-Z,0-9, 하이픈, 밑줄입니다. 피드 라벨에는 공백을 포함해서는 안 됩니다. - {OFFER_ID}: 제품의 고유 식별자입니다. 필수 항목입니다.
- {IMAGE_LINK}: 웹사이트의 제품 이미지 링크입니다. 선택사항입니다.
- {PRODUCT_LINK}: 웹사이트의 제품 링크입니다. 선택사항입니다.
- {CURRENCY_CODE}: ISO 4217에 따라 3자리 약어를 사용하여 가격의 통화를 나타냅니다. 선택사항입니다.
- {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"
}
]
}
판매자 센터 계정에 제품을 추가하려면 다음 샘플과 같이 google.shopping.merchant.accounts.v1beta.InsertProductInputSample 메서드를 사용하면 됩니다.
자바
public static void insertProductInput(Config config, String dataSource) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductInputsServiceSettings productInputsServiceSettings =
ProductInputsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify where to insert the product.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (ProductInputsServiceClient productInputsServiceClient =
ProductInputsServiceClient.create(productInputsServiceSettings)) {
// Price to be used for shipping ($33.45).
Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();
Shipping shipping =
Shipping.newBuilder()
.setPrice(price)
.setCountry("GB")
.setService("1st class post")
.build();
Shipping shipping2 =
Shipping.newBuilder()
.setPrice(price)
.setCountry("FR")
.setService("1st class post")
.build();
Attributes attributes =
Attributes.newBuilder()
.setTitle("A Tale of Two Cities")
.setDescription("A classic novel about the French Revolution")
.setLink("https://exampleWebsite.com/tale-of-two-cities.html")
.setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
.setAvailability("in stock")
.setCondition("new")
.setGoogleProductCategory("Media > Books")
.setGtin(0, "9780007350896")
.addShipping(shipping)
.addShipping(shipping2)
.build();
// The datasource can be either a primary or supplemental datasource.
InsertProductInputRequest request =
InsertProductInputRequest.newBuilder()
.setParent(parent)
// You can only insert products into datasource types of Input "API" and "FILE", and
// of Type "Primary" or "Supplemental."
// This field takes the `name` field of the datasource.
.setDataSource(dataSource)
// If this product is already owned by another datasource, when re-inserting, the
// new datasource will take ownership of the product.
.setProductInput(
ProductInput.newBuilder()
.setChannel(ChannelEnum.ONLINE)
.setContentLanguage("en")
.setFeedLabel("label")
.setOfferId("sku123")
.setAttributes(attributes)
.build())
.build();
System.out.println("Sending insert ProductInput request");
ProductInput response = productInputsServiceClient.insertProductInput(request);
System.out.println("Inserted ProductInput Name below");
// The last part of the product name will be the product ID assigned to a product by Google.
// Product ID has the format `channel~contentLanguage~feedLabel~offerId`
System.out.println(response.getName());
System.out.println("Inserted Product Name below");
System.out.println(response.getProduct());
} catch (Exception e) {
System.out.println(e);
}
}
계정에서 처리된 제품 가져오기
계정에서 처리된 제품을 검색하려면 accounts.products.get 메서드를 사용합니다. 삽입 후 처리된 제품이 표시되기까지 몇 분 정도 걸릴 수 있습니다.
GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/products/{PRODUCT_NAME}
{PRODUCT_NAME}을 삭제하려는 제품 입력 리소스의 이름으로 바꿉니다. 예를 들면 online~en~US~sku123입니다.
처리된 제품의 리소스 이름은 accounts.productInputs.insert의 응답에 있는 product 필드에서 가져올 수 있습니다.
특정 판매자 센터 계정의 단일 제품을 검색하려면 다음 샘플과 같이 google.shopping.merchant.accounts.v1beta.GetProductRequest 메서드를 사용하면 됩니다.
자바
public static void getProduct(Config config, String product) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductsServiceSettings productsServiceSettings =
ProductsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Calls the API and catches and prints any network failures/errors.
try (ProductsServiceClient productsServiceClient =
ProductsServiceClient.create(productsServiceSettings)) {
// The name has the format: accounts/{account}/products/{productId}
GetProductRequest request = GetProductRequest.newBuilder().setName(product).build();
System.out.println("Sending get product request:");
Product response = productsServiceClient.getProduct(request);
System.out.println("Retrieved Product below");
System.out.println(response);
} catch (Exception e) {
System.out.println(e);
}
}
계정에서 제품 입력 삭제하기
계정에서 제품 입력을 삭제하려면 accounts.productInputs.delete 메서드를 사용합니다. Merchant Products API를 사용하여 제품을 삭제하려면 제품이 속한 기본 또는 보조 데이터 소스의 고유 식별자를 전달해야 합니다.
다음 요청은 accounts.productInputs.delete 메서드를 사용하여 제품 입력을 삭제하는 방법을 보여줍니다.
DELETE https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/productInputs/{PRODUCT_NAME}?dataSource=accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}
{PRODUCT_NAME}을 삭제하려는 제품 입력 리소스의 이름으로 바꿉니다. 예를 들면 online~en~US~sku123입니다.
특정 판매자 센터 계정의 제품을 삭제하려면 다음 샘플과 같이 google.shopping.merchant.accounts.v1beta.DeleteProductInputRequest 메서드를 사용하면 됩니다.
자바
public static void deleteProductInput(Config config, String productId, String dataSource)
throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductInputsServiceSettings productInputsServiceSettings =
ProductInputsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates product name to identify product.
String name =
ProductInputName.newBuilder()
.setAccount(config.getAccountId().toString())
.setProductinput(productId)
.build()
.toString();
// Calls the API and catches and prints any network failures/errors.
try (ProductInputsServiceClient productInputsServiceClient =
ProductInputsServiceClient.create(productInputsServiceSettings)) {
DeleteProductInputRequest request =
DeleteProductInputRequest.newBuilder().setName(name).setDataSource(dataSource).build();
System.out.println("Sending deleteProductInput request");
productInputsServiceClient.deleteProductInput(request); // no response returned on success
System.out.println(
"Delete successful, note that it may take a few minutes for the delete to update in"
+ " the system. If you make a products.get or products.list request before a few"
+ " minutes have passed, the old product data may be returned.");
} catch (Exception e) {
System.out.println(e);
}
}
계정의 제품 나열
계정에서 처리된 제품을 나열하려면 다음 요청과 같이 accounts.products.list 메서드를 사용하세요.
GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/products
특정 판매자 센터 계정의 제품을 등록하려면 다음 샘플과 같이 google.shopping.merchant.accounts.v1beta.ListProductsRequest 메서드를 사용하면 됩니다.
자바
public static void listProducts(Config config) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductsServiceSettings productsServiceSettings =
ProductsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify the account from which to list all products.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (ProductsServiceClient productsServiceClient =
ProductsServiceClient.create(productsServiceSettings)) {
// The parent has the format: accounts/{account}
ListProductsRequest request = ListProductsRequest.newBuilder().setParent(parent).build();
System.out.println("Sending list products request:");
ListProductsPagedResponse response = productsServiceClient.listProducts(request);
int count = 0;
// Iterates over all rows in all pages and prints the datasource in each row.
// Automatically uses the `nextPageToken` if returned to fetch all pages of data.
for (Product product : response.iterateAll()) {
System.out.println(product); // The product includes the `productStatus` field
// That shows approval and disapproval information.
count++;
}
System.out.print("The following count of products were returned: ");
System.out.println(count);
} catch (Exception e) {
System.out.println("An error has occured: ");
System.out.println(e);
}
}