CSS API 권장사항
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 문서에서는 CSS API 사용과 관련된 몇 가지 권장사항을 설명합니다. 이 페이지에 제공된 조언은 API를 사용하는 데 필수적인 것은 아니지만 의도된 사용 사례를 명확히 하는 데 도움이 될 수 있습니다.
환경 설정
개발 환경을 설정하려면 빠른 시작 문서에 제공된 단계를 따르세요.
- Google Cloud 콘솔에서 사용자 및 권한 JSON 파일 생성
- Google Cloud 콘솔에서 CSS API 사용 설정
- 관리자 권한이 있는 사용자를 CSS 계정 (CSS 그룹 또는 CSS 도메인)에 추가합니다.
- 올바른 OAuth 범위(
https://www.googleapis.com/auth/content)를 사용하고 있는지 확인하세요.
이제 클라이언트 라이브러리가 대부분의 프로그래밍 언어의 표준 저장소에 있습니다. 클라이언트 라이브러리 페이지에서 목록을 확인할 수 있습니다.
올바른 ID 사용
올바른 API 엔드포인트와 함께 올바른 ID를 사용하세요.
- CSS API (
css.googleapis.com): CSS 제품과 상호작용할 때 (예:
accounts/{cssDomainId}/cssProductInputs:insert).
- Merchant API (
merchantapi.googleapis.com): 표준 판매자 제품에 Merchant API를 사용합니다.
이러한 값을 혼동하면 오류가 발생합니다. 자세한 내용은 CSS API 개요를 참고하세요.
시작하기에 적합한 방법
다음 방법으로 테스트하는 것이 좋습니다.
ListChildAccounts
ListChildAccounts는 CSS 도메인 (CSS 그룹에 대해 호출된 경우) 또는 판매자 (CSS 도메인에 대해 호출된 경우)를 모두 나열하는 읽기 전용 호출입니다. 따라서 모든 항목이 올바르게 설정되었는지 테스트하는 데 적합한 방법입니다.
제품 삽입/나열/업데이트/삭제
API 자체가 작동하는지 확인한 후 제품을 추가해 보세요. 기억할 수 있는 raw_provided_id을 사용해야 합니다.
CSS API는 병렬 호출을 위해 설계되었습니다. 단일 작업의 성능은 느릴 수 있지만 동일한 작업을 병렬로 여러 번 호출하면 훨씬 빨라집니다. 이 기능을 사용하는 가장 좋은 방법은 프로그래밍 언어의 비동기 기능을 사용하는 것입니다.
일부 프로그래밍 언어의 예:
프로그래밍 언어의 비동기 기능을 찾아 동시에 여러 제품을 삽입합니다. Google 시스템의 과부하에 대해 걱정하지 않아도 됩니다. 할당량 한도가 이를 위해 마련되어 있습니다.
자세한 내용은 성능 페이지를 참고하세요.
페이로드 검증
일반적인 오류를 방지하려면 JSON 페이로드가 올바르게 형식이 지정되었는지 확인하세요.
- 공식 문서 참고: 필드 정의, 열거형, 데이터 유형, 페이로드 구조는 항상 최신 CSS API 참조를 참고하세요.
- 샘플 페이로드 검토: 제공된 코드 샘플과 페이로드를 비교하여 불일치를 식별합니다.
- 데이터 유형: 문서에 지정된 대로 올바른 데이터 유형 (예: 문자열, 객체, 배열)을 사용하고 있는지 확인합니다.
- 점진적으로 테스트: 유효한 최소 페이로드로 시작하여 기본 연결을 확인하고 점차 속성을 추가합니다.
제품 업데이트
제품이 업로드되면 업데이트되거나 삭제되거나 만료될 때까지 Google 시스템에 유지됩니다.
- 처음에 사용한 것과 동일한
raw_provided_id을 사용하여 InsertCssProductInput 요청을 다시 전송하여 전체 제품을 업데이트할 수 있습니다. 현재는 일부 속성(예: 가격/재고)만 변경된 경우에도 전체 제품 데이터를 전송해야 합니다.
- PATCH 메서드
UpdateCssProductInput를 사용하여 제품의 일부를 업데이트할 수 있습니다. 제품 이름과 제품에 대해 업데이트할 데이터가 포함된 JSON 본문을 지정합니다. InsertCssProductInput와 달리 UpdateCssProductInput에서는 변경할 필드만 지정하면 됩니다. InsertCssProductInput에서는 적용 가능한 모든 필드를 제공해야 합니다.
- 동일한
raw_provided_id로 DeleteCssProductInput를 호출하여 제품을 삭제할 수 있습니다.
- 제품은 마지막 업데이트 후 약 1개월이 지나면 자동으로 만료됩니다.
지속 작동 모드
연속 작동 모드는 다음과 같을 수 있습니다.
- 자체 내부 ID를
raw_provided_id로 사용합니다.
- 모든 제품을 정기적으로(예: 매주) 다시 업로드합니다. 이렇게 하면 활성 제품이 만료되지 않습니다.
- 판매자로부터 변경된 데이터를 받는 즉시 개별 제품을 업데이트합니다.
- 변경사항에 즉시 대응할 수 없는 경우 변경된 제품을 자주 (예: 매시간) 찾아 해당 제품만 다시 업로드하세요.
- 더 이상 사용할 수 없는 제품의 경우 삭제 호출을 사용하거나 사용 가능한 혜택 수를 0으로 설정할 수 있습니다.
- 변경되지 않은 제품을 자주 보내지 마세요. 이러한 호출은 API 할당량에 포함됩니다. 주간 새로고침으로 충분합니다.
대표 상품 선택
대표 상품이 사이트의 최상위 제품 또는 가장 저렴한 제품일 필요는 없지만 눈에 띄게 표시되어야 합니다. 이 기능은 인기 상품이 빠르게 변하는 경우에 사용할 수 있습니다. 여기에서 더 안정적인 다른 상품을 선택할 수 있습니다.
이 문서를 가끔 다시 확인하세요
이 API를 개선하는 방법에 관한 의견을 받았으며, 이러한 개선사항을 제공하기 위해 노력하고 있습니다. CSS API 사용을 간소화하는 새로운 기능이 제공되면 이 페이지가 업데이트됩니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-13(UTC)
[null,null,["최종 업데이트: 2025-08-13(UTC)"],[[["\u003cp\u003eThis document outlines best practices for utilizing the CSS API, including setup, testing methods, performance enhancement, product management, and headline offer selection.\u003c/p\u003e\n"],["\u003cp\u003eOptimize API performance by using asynchronous calls for parallel operations, especially for inserting multiple products simultaneously.\u003c/p\u003e\n"],["\u003cp\u003eMaintain product data by regularly re-uploading all products, updating individual products as needed, and managing product expiration or deletion.\u003c/p\u003e\n"],["\u003cp\u003eThe headline offer can be strategically chosen for prominence and stability, even if it's not the cheapest or top offer on your site.\u003c/p\u003e\n"],["\u003cp\u003eStay informed about API updates and improvements by revisiting this document periodically for new features and simplified usage guidelines.\u003c/p\u003e\n"]]],[],null,["# CSS API Best Practices\n\nThis document describes some of the best practices around using the CSS API. The\nadvice given on this page is not mandatory to use the API, but may help clarify\nsome of the intended use.\n\nSetup up your environment\n-------------------------\n\nTo setup your development environment, follow the steps given from the\n[Quickstart documentation](/comparison-shopping-services/api/guides/quickstart).\n\n- Generate a user and a permissions JSON file on the Google Cloud Console\n- Enable the CSS API in the Google Cloud Console\n- Add that user with Admin permissions to your CSS Account (CSS Group or CSS Domain)\n- Verify you are using the correct OAuth scope: `https://www.googleapis.com/auth/content`\n\nClient libraries are now in the standard repositories for most programming\nlanguage. You can find a list of them on our\n[client library](/comparison-shopping-services/api/client-libraries) page.\n\nUse correct IDs\n---------------\n\nUse the correct IDs with the correct API endpoints:\n\n- **CSS API (`css.googleapis.com`):** Use the **CSS Domain ID** when interacting with CSS products (e.g., `accounts/{cssDomainId}/cssProductInputs:insert`).\n- **Merchant API (`merchantapi.googleapis.com`):** Use the Merchant API for standard merchant products.\n\nMixing these up will lead to errors. Refer to the\n[CSS API Overview](/comparison-shopping-services/api/overview) for more details.\n\nGood methods to get started\n---------------------------\n\nWe recommend testing with the following methods:\n\n### ListChildAccounts\n\n[ListChildAccounts](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.AccountsService.ListChildAccounts)\nis a read-only call that lists all of your CSS Domains (if called for a\nCSS Group) or your Merchants (if called for a CSS Domain). It is therefore a\ngood method to test if everything is setup correctly.\n\n### Insert/List/Update/Delete a product\n\nOnce you know that the API itself works, try adding a product. Make sure you use\na `raw_provided_id` that you remember.\n\n- Insert a test product using [InsertCssProductInput](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductInputsService.InsertCssProductInput). We have [sample code](/comparison-shopping-services/api/code-samples/cssproducts/insert-css-product-input) if you need help on which attributes to send.\n- List all of your products using [ListCssProducts](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductsService.ListCssProducts). There is a small processing delay before a product shows up after insertion, so if you don't see it, try again after a few seconds.\n- Update a single product using [UpdateCssProductInput](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductInputsService.UpdateCssProductInput) using your `cssproductinput.name`. You need to send only the attributes required to be updated. Refer to [sample code](/comparison-shopping-services/api/code-samples/cssproducts/update-css-product-input) here.\n- Delete the test product using [DeleteCssProductInput](/comparison-shopping-services/api/reference/rpc/google.shopping.css.v1#google.shopping.css.v1.CssProductInputsService.DeleteCssProductInput). You will need to use the `raw_provided_id`.\n\nUse Async to improve performance\n--------------------------------\n\nThe CSS API is designed for parallel calls. You will find that the performance\nof single operations can be slow, but will be much faster when calling the same\noperation multiple times in parallel. The best way to use this feature is to use\nthe async functionality of your programming language.\n\nExamples from some programming languages:\n\n- For Java, use [insertCssProductInputCallable().futureCall()](https://cloud.google.com/java/docs/reference/google-shopping-css/latest/com.google.shopping.css.v1.CssProductInputsServiceClient#com_google_shopping_css_v1_CssProductInputsServiceClient_insertCssProductInputCallable__)\n- For Python, use [CssProductInputsServiceAsyncClient](https://googleapis.dev/python/google-shopping-css/latest/css_v1/css_product_inputs_service.html)\n- For C#, use [InsertCssProductInputAsync](https://googleapis.dev/dotnet/Google.Shopping.Css.V1/latest/api/Google.Shopping.Css.V1.CssProductInputsService.CssProductInputsServiceClient.html#Google_Shopping_Css_V1_CssProductInputsService_CssProductInputsServiceClient_InsertCssProductInputAsync_Google_Shopping_Css_V1_InsertCssProductInputRequest_Grpc_Core_CallOptions_)\n\nFind and use the Async functionality of your programming language to insert\nmultiple products at the same time. You don't need to worry about overloading\nour systems - this is what the\n[quota limits](/comparison-shopping-services/api/guides/limits) are for.\n\nMore details can be found on our [performance\npage](/comparison-shopping-services/api/guides/performance).\n\nValidate Your Payloads\n----------------------\n\nTo avoid common errors, verify your JSON payloads are correctly formatted:\n\n- **Consult Official Documentation:** Always refer to the latest [CSS API reference](/comparison-shopping-services/api/reference/rest) for field definitions, enums, data types, and payload structure.\n- **Review Sample Payloads:** Compare your payloads with the provided [code samples](/comparison-shopping-services/api/code-samples) to identify discrepancies.\n- **Data Types:** Make sure you are using the correct data types (e.g., strings, objects, arrays) as specified in the documentation.\n- **Test Incrementally:** Start with minimal valid payloads to confirm basic connectivity and gradually add more attributes.\n\nUpdate a product\n----------------\n\nOnce a product is uploaded, it will stay in our system until it is either\nupdated, deleted, or expired.\n\n- You can update the full product by sending the `InsertCssProductInput` request again, using the same `raw_provided_id` you used initially. For now, you will need to send the full product data, even if only some attributes (maybe only price/availablibilty) have changed.\n- You can update parts of a product, using PATCH method `UpdateCssProductInput`, specifying product name,and a JSON body containing the data you would like to update for the product. Unlike `InsertCssProductInput`, that requires all applicable fields to be provided, `UpdateCssProductInput` only requires you to specify the fields you would like to change.\n- You can delete a product by calling `DeleteCssProductInput` with the same `raw_provided_id`.\n- Products expire automatically approximately one month after the last update.\n\nContinuous operation mode\n-------------------------\n\nA continuous operation mode could look like the following:\n\n- Use your own internal IDs as `raw_provided_id`.\n- Re-upload all products on a regular schedule, maybe weekly. This will ensure that active products don't expire.\n- Update individual products as soon as you get the changed data from your merchants.\n - If you can't react to changes immediately, find all changed products frequently (maybe hourly) and re-upload only those products.\n - For products which are no longer available, you can either use the delete call or set the number of available offers to 0.\n - Don't send us unchanged products frequently. These calls would count against your API quota. A weekly refresh is sufficient.\n\nHeadline offer selection\n------------------------\n\nThe headline offer does not necessarily need to be the top offer or the\ncheapest offer on your site, but it does need to be featured prominently. You\ncan use this for cases where your top offer is changing fast: Here you could\nselect another offer which is more stable.\n\nRe-Check this document every once in a while\n--------------------------------------------\n\nWe have received feedback on how to improve this API, and are working on making\nsome of these improvements available. This page will be updated when we have new\nfeatures available that will simplify the usage of the CSS API."]]
