권장사항
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 페이지에서는 Google Ad Manager API를 대상으로 애플리케이션을 개발할 때 고려해야 할 다양한 권장사항을 다룹니다.
실행 중에 서비스 클라이언트/스텁 재사용
새 서비스 클라이언트/스텁을 만들면 WSDL 가져오기 및 리소스 할당과 관련된 한계 비용이 발생합니다. 가능하면 실행 시작 시 서비스 클라이언트/스텁을 한 번 만들고 필요에 따라 클래스와 함수에서 사용할 수 있도록 합니다.
객체를 가져올 때 페이징 사용
모든 서비스는 PQL 구문을 사용하여 결과를 필터링할 수 있는 get*ByStatement() 메서드를 지원합니다. LIMIT 및 OFFSET 절은 큰 결과 집합을 페이지로 분할하여 시간 초과를 방지하고 응답 페이지 크기를 적정하게 유지하는 데 사용할 수 있습니다. 권장되는 페이지 크기는 객체의 복잡성에 따라 200~500입니다.
일괄 업데이트 요청
같은 유형의 여러 객체를 변경할 때 모든 객체를 동일한 update*() 요청으로 전송하여 성능을 개선할 수 있습니다. 각 요청에 대해 클라이언트와 서버에는 미미한 오버헤드가 있으며 일괄 처리는 요청 수를 줄이는 효과적인 방법이 될 수 있습니다. 예를 들어 updateOrders을 사용하여 각 호출에서 단일 주문이 아닌 일괄 주문을 업데이트합니다.
PQL에서 바인드 매개변수 사용
결합 매개변수는 PQL 쿼리 문에 변수를 입력하는 방법입니다. PQL은 콜론으로 시작하는 공백이 없는 이름으로 결합 변수를 나타냅니다(예: :name. 코드 예는 PQL 구문 페이지에서 확인할 수 있습니다.
바인드 변수를 사용하면 쿼리 문에 문자열과 변수를 연결할 필요가 없어 코드 가독성이 높아지므로 사용하는 것이 좋습니다.
또한 바인드 매개변수 값을 대체하여 새 쿼리를 생성할 수 있으므로 PQL 문을 쉽게 재사용할 수 있습니다.
사용자 권한을 최소한으로 부여
UserService를 사용하여 사용자 역할을 만들거나 업데이트할 때 사용자에게 필요 없는 권한을 부여하지 않도록 주의하세요. 사용자에게 관리자 역할을 할당하는 대신 역할 조합으로 API의 많은 기능에 액세스할 수 있습니다. 사용자에게 할당할 역할을 결정할 때는 권한 문서를 참조하세요. 또한 타사 애플리케이션 개발자는 네트워크에 사용자 생성을 요청할 때 애플리케이션에 필요한 액세스 수준을 결정해야 합니다. 관리자보다 권한이 적은 역할로도 충분할 수 있습니다.
할당량 한도 미만 유지
Ad Manager API는 견고성을 위해 몇 가지 할당량 한도를 적용합니다. 애플리케이션을 이러한 한도 이하로 유지하는 것이 중요하며 API가 반환할 수 있는 할당량 오류에 대응하는 방법을 알아야 합니다.
API 할당량
API 요청에 적용되는 첫 번째 할당량은 네트워크 수준의 할당량입니다. Ad Manager 360 계정의 경우 요청이 초당 8개로 제한되고 Ad Manager 계정의 경우 요청이 초당 2개로 제한됩니다. 이 한도를 초과하면
QuotaError.EXCEEDED_QUOTA 오류가 발생합니다. 사용자 또는 회사의 누군가가 네트워크에 대한 API 액세스 권한을 부여한 서드 파티 애플리케이션을 포함하여 네트워크에서 수행된 모든 API 요청은 이 할당량에 적용됩니다.
시스템별 할당량
API 할당량만으로는 Ad Manager 내에서 리소스를 많이 사용하는 특정 시스템을 충분히 보호하기에 충분하지 않습니다. 보고 및 예측 시스템은 API 오류를 일으킬 수 있는 자체 할당량(각각
QuotaError.REPORT_JOB_LIMIT 및
ForecastError.EXCEEDED_QUOTA)을 정의합니다.
할당량 오류 처리
애플리케이션에 위의 할당량 오류가 발생하면 API 요청을 재시도하는 전략을 실행하세요. 먼저 5초 이상 기다리는 것이 좋습니다. 오류가 계속 발생하면
지수 백오프를 사용하여 재시도 간 시간을 늘리세요. 재시도해도 문제가 해결되지 않으면 API 애플리케이션을 감사하여 네트워크에 사용자가 할당량을 소진하고 있는지 확인하세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-21(UTC)
[null,null,["최종 업데이트: 2025-08-21(UTC)"],[[["\u003cp\u003eThis page provides best practices for developing applications using the Google Ad Manager API to enhance performance and efficiency.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers should reuse service clients, use paging for large data sets, and batch update requests to optimize interactions with the API.\u003c/p\u003e\n"],["\u003cp\u003ePQL bind parameters are recommended for improved code readability and reusability, while user privileges should be granted judiciously.\u003c/p\u003e\n"],["\u003cp\u003eAd Manager API enforces quota limits; developers should implement strategies to handle quota errors and stay within allowed usage.\u003c/p\u003e\n"]]],["Optimize Google Ad Manager API usage by reusing service clients, creating them once per execution. When retrieving objects, use paging with `LIMIT` and `OFFSET` clauses, aiming for 200-500 items per page. For updates, batch multiple objects in a single request. Employ bind parameters in PQL for readability and reusability. Grant user privileges sparingly, avoiding unnecessary administrative roles. Respect quota limits, implementing retry strategies with exponential backoff, particularly for reporting and forecast requests.\n"],null,["# Best Practices\n\nThis page covers various best practices that should be considered when\ndeveloping applications against the Google Ad Manager API.\n\n- [Reuse service clients/stubs during the course of an execution](#ReuseServices)\n- [Use paging when fetching objects](#UsePaging)\n- [Batch update requests](#BatchUpdate)\n- [Store the Ad Manager API client object when appropriate](#StoreDfpUser)\n- [Use bind parameters in PQL](#UseBindParameter)\n- [Grant user privileges sparingly](#GrantUserPrivilegesSparingly)\n\n### Reuse service clients/stubs during the course of an\nexecution\n\nCreating a new service client/stub has a marginal cost associated with\nfetching the WSDL and allocating resources. If possible, create the service\nclient/stub once at the beginning of an execution and make it available to\nclasses and functions as needed.\n\n### Use paging when fetching objects\n\nAll of the services support a `get*ByStatement()` method, which\nallows for the filtering of results using [PQL](/ad-manager/api/pqlreference)\nsyntax. The `LIMIT` and `OFFSET` clauses can be used to\nsplit large result sets into pages, preventing time outs and keeping the\nresponse page sizes reasonable. The suggested page size is 200-500, depending\non the complexity of your objects.\n\n### Batch update requests\n\nWhen changing multiple objects of the same type, you can get better\nperformance by sending all of the objects in the same `update*()`\nrequest. There is a marginal overhead on the client and the server for each\nrequest, and batching can be an effective means of reducing the number of\nrequests. For example, use [`updateOrders`](/ad-manager/api/reference/latest/OrderService#updateOrders)\nto update a batch of [Orders](/ad-manager/api/reference/latest/OrderService.Order)\nrather than a single order in each call.\n\n### Use bind parameters in PQL\n\nBind parameters are a way to put variables into a PQL query statement. PQL\nrefers to a bind variable by a name without spaces starting with a colon,\ne.g., `:name`. A code example is provided in the [PQL syntax](/ad-manager/api/pqlreference#syntax) page.\n\nWe recommend using bind variables because they improve code readability by\nremoving the need to concatenate strings and variables into a query statement.\nThey also make it easy to reuse PQL statements, since new queries can be made\nby substituting the bind parameter values.\n\n### Grant user privileges sparingly\n\nWhen using [UserService](/ad-manager/api/reference/latest/UserService) to\ncreate/update user roles, be careful not to grant users privileges they do not\nneed. Many features of the API can be accessed with a combination of roles\nrather than assigning the user an administrator role. Please refer to the [permissions\ndocumentation](//support.google.com/admanager/answer/177403) when deciding which roles to assign a user. Also, as a [third party](/ad-manager/api/third-parties) application developer, make sure to\ndetermine what level of access your application needs when asking a network to\ncreate a user for you; a role with fewer privileges than administrator may be\nenough.\n\n### Stay under quota limits\n\nThe Ad Manager API enforces several quota limits for robustness. It's\nimportant to keep your applications under these limits and that you know how to\nrespond to any of the quota errors the API can return.\n\n#### API quota\n\nThe first quota applied to API requests is a network-level quota. For Ad Manager\n360 accounts, the limit is 8 requests per second, and for Ad Manager accounts,\nthe limit is 2 requests per second. Going beyond this limit results in a\n[`\nQuotaError.EXCEEDED_QUOTA`](/ad-manager/api/reference/latest/LineItemService.QuotaError#reason) error. All API requests made on your\nnetwork apply to this quota, including third-party applications that you or\nsomeone at your company has granted API access to your network.\n\n#### System-specific quotas\n\nThe API quota alone is not enough to adequately protect certain\nresource-intensive systems within Ad Manager. The reporting and forecast systems\ndefine their own quotas that can result in API errors:\n[`\nQuotaError.REPORT_JOB_LIMIT`](/ad-manager/api/reference/latest/ReportService.QuotaError#reason) and [`\nForecastError.EXCEEDED_QUOTA`](/ad-manager/api/reference/latest/ForecastService.ForecastError#reason), respectively.\n\n#### Handling quota errors\n\nIf your application encounters any of the above quota errors, carry out a\nstrategy for retrying the API request. We recommend waiting at least 5 seconds\nfirst, and if you continue to get the error, use [exponential backoff](//cloud.google.com/storage/docs/exponential-backoff#example_algorithm) to increase the time between retries. If retrying\ndoesn't succeed, perform an audit of your API applications to see if any users\non your network are draining your quota."]]
