실적 개선 도움말

이 페이지에는 애플리케이션의 성능 개선을 위해 사용할 수 있는 몇 가지 기술에 대한 설명이 나와 있습니다. 일부 경우 제시된 개념을 설명하기 위해 다른 API나 일반 API의 예가 사용되었습니다. 하지만 그 내용 자체는 Ad Exchange 구매자 REST API에 똑같이 적용할 수 있습니다.

목차

  1. gzip 사용
  2. 부분 리소스 사용
    1. 부분 응답
    2. 패치(부분 업데이트)

gzip 사용

각 요청에 필요한 대역폭을 줄이는 쉽고 편리한 방법은 gzip 압축을 가능하게 하는 것입니다. 결과물을 압축하기 위한 CPU 시간이 추가되지만 압축으로 감소하는 네트워크 비용을 고려하면 매우 효과적입니다.

gzip으로 인코딩된 응답을 받으려면 다음 두 가지 작업을 수행해야 합니다. Accept-Encoding 헤더를 설정하고 gzip 문자열을 포함하도록 사용자 에이전트를 수정합니다. 다음은 gzip 압축을 수행할 수 있도록 적절하게 만들어진 HTTP 헤더의 예입니다.

Accept-Encoding: gzip
User-Agent: my program (gzip)

부분 리소스 사용

API 요청의 실적을 개선하기 위한 또 다른 방법은 데이터의 관심 있는 부분만 송수신하는 것입니다. 이를 통해 애플리케이션이 불필요한 필드를 전송, 구문분석, 저장하는 것을 방지하여 네트워크, CPU, 메모리 등의 리소스를 효율적으로 사용할 수 있게 합니다.

부분 요청은 다음 두 가지 유형으로 구분됩니다.

  • 부분 응답 - fields 요청 매개변수를 사용하여 응답에 포함될 필드를 명시하는 요청입니다.
  • 패치 - PATCH HTTP 동사를 사용하여 변경할 필드만 전송하는 업데이트 요청입니다.

부분 요청에 대한 자세한 내용은 다음 섹션에서 확인하실 수 있습니다.

부분 응답

기본적으로 서버는 요청을 처리한 후 전체 리소스를 반환합니다. 성능을 개선하기 위해 서버에 필요한 필드만 전송하도록 요청하여 부분 응답을 받아볼 수 있습니다.

부분 응답을 요청하려면 fields 요청 매개변수를 사용하여 응답을 원하는 필드를 지정합니다. 응답 데이터를 반환하는 모든 요청에서 이 매개변수를 사용할 수 있습니다.

fields 매개변수는 응답 데이터에만 영향을 줄 뿐이고 보내야 하는 데이터에는 영향을 주지 않습니다. 리소스를 수정할 때 보내는 데이터의 양을 줄이려면 패치 요청을 사용하세요.

다음은 일반(가상) '데모' API가 포함된 fields 매개변수의 사용을 보여주는 예입니다.

단순 요청: 이 HTTP GET 요청은 fields 매개변수를 생략하고 전체 리소스를 반환합니다.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY

전체 리소스 응답: 전체 리소스 데이터에는 줄여서 생략한 내용과 다음의 필드가 포함됩니다.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

부분 응답 요청: 같은 리소스에 대한 다음의 요청은 반환된 데이터의 양을 확실히 줄이기 위해 fields 매개변수를 사용합니다. 

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

 부분 응답: 상기의 요청에 대해 서버는 각 항목의 HTML 제목과 길이 특성 정보만 포함된 요약 항복 배열과 종류 정보만 들어 있는 응답을 반송합니다. 

200 OK

{
  "kind": "demo",
  "items": [
  {
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  },
  {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]

해당 응답은 선택된 필드와 이를 포괄하는 상위 객체만이 포함된 JSON 객체임을 유의하세요.

아래에 fields 매개변수의 형식을 지정하는 방법 및 응답으로 반환되는 정확한 값에 대한 자세한 설명이 나와 있습니다.

필드 매개변수 구문 요약

fields 요청 매개변수의 형식은 기본적으로 XPath 구문을 바탕으로 합니다. 아래는 지원되는 구문을 요약한 내용이며, 추가 샘플은 다음 섹션을 참조하세요.

  • 여러 필드를 선택하려면 쉼표로 구분하여 입력하세요.
  • 필드 a에 삽입된 필드 b를 선택하려면 a/b를 사용하고, b에 삽입된 필드 c를 선택하려면 a/b/c를 사용하세요.

    예외: '데이터' 래퍼를 사용하는 API 응답에 대해 data: { ... }와 같은 data 객체에 삽입된 응답의 경우 fields 사양에 'data'를 포함하지 않습니다. data/a/b와 같이 data 객체를 포함하여 필드를 지정하면 오류가 발생합니다. 대신 a/b와 같이 fields를 지정합니다.

  • 하위 선택자를 사용하여 어레이 또는 객체의 특정 하위 필드의 조합을 요청하려면 '( )'와 같이 괄호 안에 표현식을 입력합니다.

    예: fields=items(id,author/email)은 항목 배열에서 각 요소에 대한 항목 ID와 작성자의 이메일만을 반환합니다. 단일 하위 필드도 지정할 수 있으며, fields=items(id)fields=items/id와 같습니다.

  • 필요할 경우 임의 문자 기호를 사용하여 필드를 선택합니다.

    예:fields=items/pagemap/*은 페이지맵의 모든 객체를 선택합니다.

필드 매개변수를 사용한 예

아래 예에서는 fields 매개변수 값이 응답에 미치는 영향에 대해 설명합니다.

참고: 모든 쿼리 매개변수와 마찬가지로 fields 매개변수는 반드시 URL 인코딩해야 합니다. 더 쉽게 확인할 수 있도록 이 예에는 인코딩이 생략되어 있습니다.

응답을 원하는 필드를 지정하거나 필드 선택을 수행합니다.
fields 요청 매개변수 값은 쉼표로 구분된 필드의 목록이며, 각 필드는 응답의 루트에 대한 상대적인 값으로 지정됩니다. 따라서 list 연산을 수행하면 응답은 컬렉션이 되며, 일반적으로 리소스의 배열이 포함됩니다. 단일 리소스를 반환하는 연산을 수행할 경우 필드는 리소스에 대한 상대적인 값으로 지정됩니다. 선택할 필드가 배열이거나 배열의 일부인 경우 서버는 배열에 모든 요소 부분을 반환합니다.

다음은 컬렉션 수준의 예입니다.
결과
items 각 요소의 모든 필드를 포함해 items 배열의 모든 요소를 반환하지만, 그 외의 필드는 반환하지 않습니다.
etag,items etag 필드 및 items 배열의 모든 요소를 반환합니다.
items/title items 배열의 모든 요소에 대한 title 필드만을 반환합니다. 

중첩 필드가 반환될 때마다 응답에는 그 상위 객체가 포함됩니다. 분명하게 선택하지 않으면 상위 필드에는 다른 하위 필드가 포함되지 않습니다.
context/facets/label context 객체의 하위 객체인 facets 배열의 모든 구성원에 대해 label 필드만 반환합니다.
items/pagemap/*/title items 배열의 각 요소에 대해 pagemap의 모든 하위 객체에 대해 title 필드(있을 경우)만 반환합니다.

다음은 리소스 수준의 예입니다.
결과
title 요청된 리소스의 title 필드를 반환합니다.
author/uri 요청된 리소스에서 author 객체의 하위 필드인 uri를 반환합니다.
links/*/href
links의 모든 하위 객체에 대해 href 필드를 반환합니다.
하위 선택을 사용하여 특정 필드의 일부만 요청합니다. 
기본값으로 특정 필드를 명시해서 요청했다면 서버는 전체에서 해당 객체나 배열 요소를 반환합니다. 특정 하위 필드가 포함된 응답을 명시할 수 있습니다. 아래 예에서와 같이'( )' 하위 선택 구문을 사용하면 됩니다.
결과
items(title,author/uri) items 배열의 각 요소에 대해 title 및 author의 uri 값만 반환합니다.

부분 응답 처리

서버는 fields 쿼리 매개변수가 포함된 유효한 요청을 처리한 후 요청된 데이터와 함께 HTTP 200 OK 상태 코드를 반환합니다. fields 쿼리 매개변수에 오류가 있거나, 유효하지 않은 경우, 서버는 'Invalid field selection a/b'와 같은 필드 선택사항에 사용자에게 잘못된 내용을 설명하는 오류 메시지와 함께 HTTP 400 Bad Request 상태 코드를 반환합니다. 

다음은 위의 소개 섹션에 나온 부분 응답의 예입니다. 해당 요청은 반환될 필드가 어떤 필드인지 명시하는 fields 매개변수를 사용합니다.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

부분 응답의 코드는 다음과 같습니다.

200 OK

{
  "kind": "demo",
  "items": [
  {
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  },
  {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]

참고: maxResults, nextPageToken과 같이 데이터 페이지 번호에 대해 검색어 매개변수를 지원하는 API의 경우 관리 가능한 크기까지 각 검색어 결과를 줄일 수 있는 매개변수를 사용하세요. 이렇게 하지 않으면 부분 응답으로 인한 성능 개선 효과를 얻지 못할 수도 있습니다.

패치(부분 업데이트)

리소스 수정 시 불필요한 데이터 송신을 피할 수 있습니다. 변경하는 특정 필드에 대해서만 업데이트된 데이터를 보내려면 HTTP PATCH 동사를 사용하세요. 여기에 설명된 패치 시맨틱스는 이전 버전의 부분 업데이트의 GData 구현과 다르며 더 간단합니다.

다음은 어떻게 패치를 사용하느냐에 따라 송신 데이터를 최소화할 수 있는지 보여주는 예입니다.

이 예는 일반(허구의) '데모' API 리소스의 제목만을 업데이트하기 위한 간단한 패치 요청입니다. 리소스는 의견, 특성 세트, 상태, 그 외의 많은 필드도 가지고 있지만, 이 요청은 유일하게 수정하는 필드인 title 필드만을 보냅니다.

PATCH https://www.googleapis.com/demo/v1/324
Authorization: /*Auth token goes here*/
Content-Type: application/json

{
  "title": "New title"
}

응답:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

서버는 업데이트된 리소스의 전체 표현과 200 OK 상태 코드를 반환합니다. title 필드만 패치 요청에 포함되었으므로 이 값만 이전과 다릅니다.

참고: 패치와 결합하여 부분 응답 fields 매개변수를 사용하면 업데이트 요청의 효율을 더 향상시킬 수 있습니다. 패치 요청은 요청의 크기만 줄입니다. 부분 응답은 응답의 크기를 줄입니다. 따라서 양방향으로 보낸 데이터의 양을 줄이려면 fields 매개변수를 포함하는 패치를 사용하세요.

패치 요청의 시맨틱스

패치 요청의 본문에는 수정하고자 하는 리소스 필드만이 포함됩니다. 부분 응답과 함께 동봉한 상위 객체가 반환되는 것처럼 필드를 지정할 때 반드시 동봉한 상위 객체를 포함해야 합니다. 상위 객체가 하나이면 보내는 수정 데이터가 상위 객체에 대한 데이터로 합병됩니다.

  • 추가: 존재하지 않는 필드를 추가하려면 새로운 필드와 해당 값을 지정하세요.
  • 수정: 기존 필드의 값을 변경하려면 해당 필드를 지정하고 새 값으로 설정하세요.
  • 삭제: 필드를 삭제하려면 해당 필드를 지정하고 null로 설정하세요. 예를 들어 "comment": null과 같이 설정하면 됩니다. 또한 전체 객체의 변경이 용이한 경우 전체 객체를 null로 설정하여 삭제할 수도 있습니다.

배열에 대한 참고사항: 배열을 포함하는 패치 요청은 기존 배열을 귀하가 제공하는 배열로 교체합니다. 단편적인 방법으로 배열의 항목을 수정, 추가, 삭제할 수 없습니다.

읽기-수정-쓰기 사이클에서 패치 사용

수정하고자 하는 데이터를 포함해 부분 응답을 검색하는 것으로 시작하는 유용한 사례가 될 수 있습니다. 리소스를 성공적으로 업데이트하려면 If-Match HTTP 헤더에 현재의 ETag 값을 넣어야 하므로 ETag를 사용하는 리소스에 특히 중요합니다. 데이터를 얻은 후에는 변경할 값을 수정하고 수정된 부분 표현을 패치 요청과 함께 돌려 보낼 수 있습니다. 다음은 ETag를 이용하는 데모 리소스를 가정한 예입니다.

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: /*Auth 토큰을 여기에 입력합니다.*/

다음은 부분 응답입니다.

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

다음의 패치 요청은 해당 응답을 토대로 합니다. 아래와 같이 패치 응답에서 반환되는 데이터를 제한하기 위해 fields 매개변수도 사용합니다.

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: /* Auth 토큰을 여기에 입력합니다. */
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* 제목을 빈 문자열로 설정하여 제목값을 지웁니다. */
  "comment": null,              /* 의견값을 null로 수정하여 의견을 삭제합니다. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* 수준값을 수정합니다. */
    "followers": ["Jo", "Liz"], /* Will을 삭제하고 Liz를 추가하도록 팔로어 배열을 교체합니다. */
    "accuracy": "high"          /* 새 특성을 추가합니다. */
  },
}

서버는 200 OK HTTP 상태 코드와 업데이트된 리소스 전체에 응답합니다.

200 OK

{
  "etag": "
newETagString
"
  "title": "",                 /* 제목이 지워집니다. 삭제된 의견 필드가 없어집니다. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* 값이 업데이트됩니다.*/
    "followers": ["Jo" "Liz"], /* 새 팔로어인 Liz가 남아 있고 삭제된 Will은 없어집니다. */
    "accuracy": "high"         /* 새 특성이 나타납니다.. */
  }
}

패치 요청 직접 구성

일부 패치 응답은 이전에 검색한 데이터를 토대로 해야 합니다. 예를 들어, 기존 배열 요소 항목은 잃지 않고 어떤 배열에 새로운 항목을 추가하고자 하는 경우, 반드시 기존 데이터를 먼저 구해야 합니다. 이와 비슷하게 API가 ETag를 사용하는 경우 리소스를 성공적으로 업데이트하기 위해 요청과 함께 이전 ETag 값을 보내야 합니다.

참고: ETag 사용 시 패치가 통과되도록 강제하는 'If-Match: *' HTTP 헤더를 사용할 수 있습니다. 이렇게 하면, 쓰기 전에 읽지 않아도 됩니다.

하지만, 다른 상황인 경우 먼저 기존 데이터를 검색하지 않고 직접 패치 요청을 구성할 수 있습니다. 예를 들어 새로운 값으로 필드를 업데이트하거나 새로운 필드를 추가하는 패치 요청을 쉽게 설정할 수 있습니다. 예를 들면 다음과 같습니다.

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: /* Auth 토큰을 여기에 입력합니다. */
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

이 요청과 함께 의견 필드가 기존의 값을 가지는 경우 새로운 값으로 덮어쓰기를 하며, 그렇지 않은 경우 새로운 값으로 설정합니다. 이와 비슷하게 거래량 특성이 있었던 경우 값을 덮어쓰기하며, 그렇지 않은 경우 새로 생성합니다. 설정된 경우 정확성 필드는 삭제됩니다.

패치 응답 처리

유효 패치 요청을 처리한 후 API가 수정된 리소스의 전체 표현과 함께 200 OK HTTP 응답 코드를 반환합니다. ETag를 API에서 사용하면 서버가 PUT에서처럼 패치 요청을 성공적으로 처리할 때 ETag 값을 업데이트합니다.

반환되는 데이터 양을 줄이기 위해 fields 매개변수를 사용하지 않는 경우가 아니면 패치 요청에서 전체 전체 리소스 표현을 반환합니다.

패치 요청에 의해 구문적으로 또는 의미상으로 잘못된 새 리소스 상태가 생긴 경우 서버는 400 Bad Request 또는 422 Unprocessable Entity HTTP 상태 코드를 반환하며, 리소스 상태는 변경되지 않은 채로 유지됩니다. 예를 들어 필수 필드 값을 지우려고 하면 서버에서 오류가 반환됩니다.

PATCH HTTP 동사가 지원되지 않을 대의 대체 표기법

방화벽이 HTTP PATCH 요청을 허용하지 않으면 아래에 나온 것처럼 HTTP POST 요청을 하고 우선 적용 헤더를 PATCH로 설정하세요.

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

패치와 업데이트의 차이점

실제로 HTTP PUT 동사를 사용하는 업데이트 요청에 대해 데이터를 보내는 경우 필수 또는 선택인 필드만을 보내야 합니다. 서버에 의해 설정된 필드 값을 보내면 해당 값은 무시됩니다. 이것이 부분 업데이트의 또 다른 방법이지만 다소 제한적입니다. HTTP PUT 동사를 사용하는 업데이트에서는 필수 매개변수를 제공하지 못하면 요청이 실패하고, 선택 매개변수를 제공하지 못하면 이전에 설정한 데이터가 지워집니다.

이러한 이유로 패치를 사용하는 것이 훨씬 더 안전합니다. 변경하고자 하는 필드의 데이터만 제공하며, 생략하고자 하는 필드는 지워지지 않습니다. 이 규칙에 대한 유일한 예외내용은 요소나 배열을 반복함에 따라 발생합니다. 이들 중 모두를 생략하는 경우 이전처럼 유지되며 이들 중 일부를 제공하는 경우 전체 세트는 제공한 세트로 대체됩니다.

다음에 대한 의견 보내기...

DoubleClick Ad Exchange Buyer REST API