일괄 처리를 위한 한 가지 구체적인 접근 방식인 Global HTTP Batch 엔드포인트(www.googleapis.com/batch)는 Google Developers 블로그에 공지된 바와 같이 2020년 8월 12일부로 종료되었습니다. 이 페이지의 나머지 부분에서 설명하고 있듯이, 다른 일괄 처리 방법도 여전히 사용 가능합니다. 코드가 Global HTTP Batch 엔드포인트를 사용하는 경우 블로그 게시물을 참조하여 API별 HTTP Batch 엔드포인트(www.googleapis.com/batch/API/VERSION) 등, 다른 접근 방식을 사용하도록 전환하는 방법을 확인하세요.
이 문서에서는 API 호출을 일괄 처리하여 클라이언트가 수행해야 하는 HTTP 연결 수를 줄이는 방법을 보여줍니다.
이 문서에서는 특히 HTTP 요청을 보내 일괄 요청을 만드는 방법에 대해 설명합니다. 대신 Google 클라이언트 라이브러리를 사용하여 일괄 요청을 하는 경우 클라이언트 라이브러리 문서를 참조하세요.
개요
클라이언트가 수행하는 각 HTTP 연결에는 어느 정도의 오버헤드가 수반됩니다. Google Ad Experience Report API는 일괄 처리를 지원하므로 클라이언트에서 단일 HTTP 요청에 여러 API 호출을 넣을 수 있습니다.
다음과 같은 경우에 일괄 처리를 사용할 수 있습니다.
- API를 이제 막 사용하기 시작했고 업로드할 데이터가 많습니다.
- 애플리케이션이 오프라인인 상태에서(인터넷 연결이 끊김) 사용자가 데이터를 변경했기 때문에 애플리케이션에서 많은 업데이트와 삭제를 전송하여 로컬 데이터와 서버를 동기화해야 합니다.
각 경우에 각 호출을 개별적으로 보내는 대신 하나의 HTTP 요청으로 그룹화할 수 있습니다. 모든 내부 요청은 동일한 Google API로 이동해야 합니다.
단일 일괄 요청에서 호출 수는 1,000개로 제한됩니다. 이보다 더 많은 호출을 해야 한다면 일괄 요청을 여러 개 사용하세요.
참고: Google Ad Experience Report API용 일괄 처리 시스템은 OData 일괄 처리 시스템과 동일한 구문을 사용하지만 시맨틱스는 다릅니다.
일괄 처리 세부정보
일괄 요청은 하나의 HTTP 요청으로 결합된 여러 API 호출로 구성되며, 이 요청을 API 검색 문서에 지정된 batchPath로 보낼 수 있습니다. 기본 경로는 /batch/api_name/api_version입니다. 이 섹션에서는 일괄 처리 구문을 세부적으로 설명하며 뒷부분에서 예시를 제시합니다.
참고: n 요청 한 묶음은 사용량 한도가 한 요청이 아니라 n 요청으로 계산됩니다. 일괄 요청은 처리 전에 일련의 요청으로 분할됩니다.
일괄 요청의 형식
일괄 요청은 여러 개의 Google Ad Experience Report API 호출을 포함하는 단일 표준 HTTP 요청이며 multipart/mixed 콘텐츠 유형을 사용합니다. 이 기본 HTTP 요청 내의 각 부분에 중첩된 HTTP 요청이 포함됩니다.
각 부분은 자체 Content-Type: application/http HTTP 헤더로 시작됩니다. 선택사항인 Content-ID 헤더가 있는 경우도 있습니다. 그러나 부분 헤더는 부분의 시작을 표시하기 위해 있을 뿐이며 중첩된 요청과는 별개입니다. 서버에서 일괄 요청을 개별 요청으로 해체하면 부분 헤더는 무시됩니다.
각 부분의 본문은 자체 동사와 URL, 헤더, 본문을 포함하며 그 자체로 완전한 HTTP 요청입니다. HTTP 요청은 URL의 경로 부분만 포함해야 합니다. 전체 URL은 일괄 요청에서 허용되지 않기 때문입니다.
외부 일괄 요청의 HTTP 헤더(Content-Type과 같은 Content- 헤더 제외)는 일괄 처리되는 각 요청에 모두 적용됩니다. 특정 HTTP 헤더를 외부 요청과 개별 호출에 모두 지정하는 경우 개별 호출 헤더의 값이 외부 일괄 요청 헤더의 값을 재정의합니다. 개별 호출의 헤더는 해당 호출에만 적용됩니다.
예를 들어 특정 호출에 승인 헤더를 제공하는 경우 이 헤더는 해당 호출에만 적용됩니다. 외부 요청에 승인 헤더를 제공하는 경우 이 헤더는 개별 호출에서 자체 승인 헤더로 재정의하지 않는 이상 모든 개별 호출에 적용됩니다.
서버는 일괄 요청을 수신하면 외부 요청의 쿼리 매개변수와 헤더를 각 부분에 적절히 적용한 다음 각 부분을 개별 HTTP 요청처럼 취급합니다.
일괄 요청 응답
서버 응답은 multipart/mixed 콘텐츠 유형의 단일 표준 HTTP 응답입니다. 각 부분은 일괄 요청에 포함된 요청 중 하나에 대한 응답이며 요청 순서와 동일한 순서로 표시됩니다.
요청의 부분과 마찬가지로 각 응답 부분에는 상태 코드, 헤더, 본문을 포함한 완전한 HTTP 응답이 포함됩니다. 또한 요청의 부분과 마찬가지로 각 응답 부분 앞에는 Content-Type 헤더가 붙어 부분의 시작을 표시합니다.
요청의 특정 부분에 Content-ID 헤더가 있는 경우 해당하는 응답 부분에도 일치하는 Content-ID 헤더가 표시되며 원래 값 앞에는 문자열 response-가 붙습니다(다음 예시 참조).
참고: 서버는 호출을 임의의 순서로 수행할 수 있습니다. 지정한 순서에 따라 실행된다고 생각하면 안 됩니다. 2개의 호출이 지정된 순서에 따라 실행되도록 하려면 1개의 요청으로 두 호출을 보내면 안 됩니다. 첫 번째 호출을 단독으로 보낸 다음 첫 번째 호출의 응답을 기다렸다가 두 번째 호출을 보내야 합니다.
예
다음 예는 Google Ad Experience Report API를 사용한 일괄 처리를 사용하는 방법을 보여줍니다.
일괄 요청 예시
POST /batch/v1?key=key HTTP/1.1 Content-Type: multipart/mixed; boundary=batch_aer --batch_aer Content-Type: application/http Content-ID: id1 GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1 --batch_aer Content-Type: application/http Content-ID: id2 GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1 --batch_aer--
일괄 응답 예시
이전 섹션의 요청 예시에 대한 응답입니다.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_aer
--batch_aer
Content-Type: application/http
Content-ID: response-id1
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site1",
"mobileSummary": {
"lastChangeTime": "2019-02-05T09:46:26.521747Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2019-02-07T23:07:29.017206Z",
"betterAdsStatus": "FAILING",
"enforcementTime": "2018-02-15T15:00:00Z",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
"filterStatus": "ON"
}
}
--batch_aer
Content-Type: application/http
Content-ID: response-id2
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site2",
"mobileSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
"filterStatus": "OFF"
}
}
--batch_aer--