이 페이지는 Cloud Translation API를 통해 번역되었습니다.

차트 도구 데이터 소스 프로토콜 (V0.6) 구현

이 페이지에서는 쿼리 클래스를 사용하여 차트에 데이터를 노출하도록 차트 도구 데이터 소스 프로토콜을 지원하는 서비스를 구현하는 방법을 설명합니다.

시청자층

이 페이지는 주로 차트 도구 데이터 소스 라이브러리를 사용하지 않고 자체 데이터 소스를 만드는 개발자를 대상으로 합니다. 해당 라이브러리 또는 다른 도우미 라이브러리를 사용하는 경우 먼저 라이브러리의 문서를 읽어보세요.

이 페이지는 클라이언트 시각화와 데이터 소스 간의 통신에 사용되는 유선 프로토콜을 이해하는 데 관심이 있는 독자를 대상으로 합니다.

시각화를 만들거나 사용하는 경우에는 이 페이지를 읽지 않아도 됩니다.

이 문서를 읽으려면 기본 JSON 및 HTTP 요청 구문을 이해하고 있어야 합니다. 또한 사용자 관점에서 차트 작동 방식을 이해해야 합니다.

참고: Google은 차트 도구 데이터 소스 프로토콜을 지원하는 Google 이외의 데이터 소스를 공식적으로 보증하거나 지원하지 않습니다.

개요

차트 도구 데이터 소스 프로토콜을 구현하여 내 차트나 다른 차트의 데이터 소스 제공자가 될 수 있습니다. 차트 도구 데이터 소스는 차트에서 HTTP GET 요청을 보낼 수 있는 데이터 소스 URL이라는 URL을 노출합니다. 이에 대한 응답으로 데이터 소스는 차트가 페이지에서 그래픽을 렌더링하는 데 사용할 수 있는 올바른 형식의 데이터를 반환합니다. 이러한 요청-응답 프로토콜을 Google 시각화 API 유선 프로토콜이라고 합니다.

데이터 소스에서 제공하는 데이터는 파일 또는 데이터베이스와 같은 다양한 리소스에서 추출할 수 있습니다. 유일한 제한사항은 데이터의 형식을 유형이 지정된 열이 있는 2차원 테이블로 지정할 수 있다는 것입니다.

차트 도구 데이터 소스는 특정 형식으로 요청을 파싱하고 특정 형식으로 응답을 반환해야 합니다. 다음과 같은 두 가지 일반적인 방법 중 하나로 확인할 수 있습니다.

다음 도우미 라이브러리 중 하나를 사용하여 요청 및 응답을 처리하고 반환할 DataTable을 구성합니다. 이러한 라이브러리 중 하나를 사용하는 경우 데이터를 테이블 형식으로 라이브러리에서 사용할 수 있도록 하는 데 필요한 코드만 작성하면 됩니다.
- 자바 데이터 소스 라이브러리 - 요청 및 응답을 처리하고, 제공된 데이터로 응답 테이블을 만들고, Google 차트 도구 SQL 쿼리 언어를 구현합니다.
- Python 데이터 소스 라이브러리 - 응답 구문을 생성하는 응답 테이블을 만듭니다. 요청 파싱 또는 Google Chart Tools SQL 쿼리 언어 구현을 처리하지 않습니다.
  
  또는
요청을 처리하고, DataTable을 작성하고, 응답을 전송하여 자체 데이터 소스를 처음부터 작성합니다.

작동 방식:

데이터 소스는 차트에서 HTTP GET 요청을 보내는 데이터 소스 URL이라는 URL을 노출합니다.
클라이언트는 반환된 데이터에 사용할 형식, 선택적 쿼리 문자열, 선택적 커스텀 매개변수를 설명하는 매개변수를 사용하여 HTTP GET 요청을 합니다.
데이터 소스가 요청 형식에 설명된 대로 요청을 수신하고 파싱합니다.
데이터 소스는 요청된 형식으로 데이터를 준비합니다. 일반적으로 JSON 테이블입니다. 응답 형식은 응답 형식 섹션에서 다룹니다. 데이터 소스는 필터링, 정렬, 기타 데이터 조작을 지정하는 시각화 API 쿼리 언어를 선택적으로 지원할 수 있습니다.
데이터 소스가 직렬화된 데이터와 기타 응답 매개변수를 포함하는 HTTP 응답을 만들고 응답 형식에 설명된 대로 클라이언트로 다시 전송합니다.

참고: 요청 및 응답에 관해 이 문서에 나열된 모든 매개변수와 문자열 상수 값 (예: responseHandler 및 'ok')은 소문자이며 대소문자를 구분합니다.

최소 요건

차트 도구 데이터 소스로 사용하기 위한 최소 요구사항은 다음과 같습니다.

데이터 소스가 HTTP GET 요청을 수락하고 클라이언트에서 사용할 수 있어야 합니다.
프로토콜은 변경될 수 있고 버전 체계 (현재 버전은 0.6)를 지원하므로 데이터 소스는 이전 버전과 현재 버전을 사용하는 요청을 지원해야 합니다. 최신 버전으로 빠르게 업그레이드하는 클라이언트가 중단되지 않도록 새 버전이 출시되자마자 지원해야 합니다.
알 수 없는 속성이 요청의 일부로 전송되더라도 실패하지 않습니다. 이는 새 버전에서는 사용자가 알지 못하는 새 속성이 생길 수 있기 때문입니다.
예상되는 속성만 파싱합니다. 새 버전이 새 속성을 사용할 수도 있지만 맹목적으로 전체 요청 문자열을 수락하여 사용하지 마세요. 악의적인 공격으로부터 자신을 보호하려면 신중하게 파싱하여 예상되는 속성만 사용하세요.
클라이언트 차트를 직접 코딩하지 않는 경우 데이터 소스 요구사항을 신중하게 문서화합니다. 여기에는 다음 정보를 문서화하는 것이 포함됩니다.
- 허용되는 모든 맞춤 매개변수와
- Google 시각화 API 쿼리 언어를 파싱할 수 있는지 여부
- 반환하는 데이터의 종류 및 해당 데이터의 구조 (행과 열이 나타내는 내용, 라벨 지정).
알 수 없는 클라이언트의 요청을 수락하는 사이트에는 모든 표준 보안 예방 조치를 취하세요. 매개변수에서 MD5, 해싱, 기타 보안 메커니즘을 합리적으로 지원하여 요청을 인증하거나 악의적인 공격으로부터 보호하고 클라이언트가 요구사항을 인식하고 이에 응답할 것으로 기대할 수 있습니다. 하지만 차트를 직접 코딩하지 않는다면 모든 요구사항을 잘 문서화해야 합니다. 아래의 보안 고려사항을 참조하세요.
모든 요청 및 응답 문자열은 UTF-8로 인코딩되어야 합니다.
가장 중요한 응답 형식은 JSON입니다. JSON은 대부분의 차트에서 사용하는 형식이므로 먼저 JSON을 구현해야 합니다. 나중에 다른 응답 유형을 추가하세요.
시각화 API 쿼리 언어를 필수적으로 지원할 필요는 없지만 이렇게 하면 데이터 소스가 고객에게 더 유용해집니다.
모든 차트 유형의 요청을 반드시 지원해야 하는 것은 아니며 커스텀 차트용 커스텀 매개변수를 지원할 수 있습니다. 하지만 아래에 설명된 표준 형식으로 응답을 반환해야 합니다.

보안 고려사항

데이터 소스를 설계할 때는 데이터의 보안 정도를 고려해야 합니다. 간단한 비밀번호 액세스에서 안전한 쿠키 인증에 이르기까지 사이트에 다양한 보안 체계를 사용할 수 있습니다.

차트와 함께 XSSI (교차 사이트 스크립트 포함) 공격은 위험합니다. 사용자가 악성 스크립트가 포함된 페이지로 이동한 후 현재 사용자의 사용자 인증 정보를 사용하여 데이터 소스 URL에 쿼리를 실행하기 시작할 수 있습니다. 사용자가 사이트에서 로그아웃하지 않은 경우 스크립트가 현재 사용자로 인증되고 해당 사이트에 대한 권한이 부여됩니다. <script src> 태그를 사용하면 악성 스크립트가 JSONP와 유사하게 데이터 소스를 포함할 수 있습니다.

보안 강화를 위해 데이터 소스와 동일한 도메인에서 발생하는 요청으로 요청을 제한할 수 있습니다. 이렇게 하면 데이터 소스의 공개 상태가 상당히 제한되지만, 도메인 외부에서 액세스해서는 안 되는 매우 민감한 정보가 있는 경우에는 이 점을 고려해야 합니다. 동일한 도메인의 요청만 허용하는 데이터 소스를 모든 도메인의 쿼리를 허용하는 무제한 데이터 소스와 달리 제한된 데이터 소스라고 합니다. 다음은 제한된 데이터 소스를 구현하는 방법에 관한 세부정보입니다.

외부 도메인 (또는 XSRF 공격을 받고 있는 도메인 내부의 브라우저)이 아니라 도메인 내에서 요청이 전송되었는지 확인하려면 다음 단계를 따르세요.

요청에 'X-DataSource-Auth' 헤더가 있는지 확인합니다. 이 헤더는 Google 시각화 API에 의해 정의되며, 이 헤더의 콘텐츠를 검사할 필요 없이 정보가 있는지만 확인하면 됩니다. Google 차트 도구 데이터 소스 라이브러리를 사용하는 경우 라이브러리에서 이 작업을 처리하도록 할 수 있습니다.
쿠키 인증을 사용하여 클라이언트를 인증합니다. 인증 쿠키를 유지하면서 커스텀 헤더를 교차 도메인 요청에 삽입하는 방법은 알려진 것이 없습니다.
<script src> 태그와 함께 포함된 경우 자바스크립트가 실행되지 않게 합니다. 이렇게 하려면 JSON 응답에 )]}' 프리픽스를 붙이고 그 뒤에 줄바꿈을 붙입니다. 클라이언트에서 응답의 프리픽스를 삭제합니다. XmlHttpRequest의 경우 요청이 동일한 도메인에서 시작된 경우에만 가능합니다.

요청 형식

클라이언트가 커스텀 요소, 선택적 쿼리 문자열, 서명, 기타 요소를 비롯한 여러 매개변수와 함께 HTTP GET 요청을 보냅니다. 개발자는 이 섹션에 설명된 매개변수를 파싱하는 작업만 수행해야 하며 악의적인 공격을 피하기 위해 다른 매개변수를 처리하지 않도록 주의해야 합니다.

선택적 매개변수 (표준 및 커스텀)의 기본값을 지정하고 사이트 문서에 모든 기본값을 문서화합니다.

다음은 몇 가지 요청 샘플입니다. 이 문서의 끝부분에 있는 예시에서 더 많은 요청 및 응답 샘플을 확인할 수 있습니다.

참고: 다음 요청 문자열과 예시 섹션에 표시된 문자열은 전송하기 전에 URL을 이스케이프 처리해야 합니다.

Basic request, no parameters:
http://www.example.com/mydatasource

Request with the tqx parameter that contains two properties:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Request with a query string:
http://www.example.com/mydatasource?tq=limit 1

다음은 요청 문자열의 모든 표준 매개변수 목록입니다. 매개변수 이름 (예: 'version')과 상수 문자열 값(예: 'ok', 'warning', 'not_modify')은 모두 대소문자를 구분합니다. 이 표에서는 매개변수를 전송해야 하는지 여부와 매개변수를 전송해야 하는 경우 이를 처리해야 하는지 여부도 설명합니다.

매개변수

매개변수	요청에 필수 여부	데이터 소스 처리 대상	설명
TQ	아니요	아니요	Google 시각화 API 쿼리 언어로 작성된 쿼리로, 반환된 데이터를 필터링, 정렬 또는 조작하는 방법을 지정합니다. 문자열은 따옴표로 묶지 않아도 됩니다. 예: `http://www.example.com/mydatasource?tq=select Col1`
TQX	아니요	예	표준 또는 맞춤 매개변수의 콜론으로 구분된 키-값 쌍 집합입니다. 각 쌍을 세미콜론으로 구분합니다. 다음은 시각화 프로토콜에서 정의하는 표준 매개변수 목록입니다. `reqId` - [요청 시 필요, 데이터 소스에서 처리해야 함] 이 요청의 숫자 식별자입니다. 클라이언트가 응답을 받기 전에 여러 요청을 보내는 경우 데이터 소스가 적절한 요청으로 응답을 식별할 수 있도록 하기 위해 사용됩니다. 이 값을 응답으로 다시 보냅니다. `version` - [요청 시 선택사항, 데이터 소스에서 처리해야 함] Google 시각화 프로토콜의 버전 번호입니다. 현재 버전은 0.6입니다. 전송하지 않았다면 최신 버전으로 가정합니다. `sig` - [요청 시 선택사항, 처리할 데이터 소스에서 선택사항] 이 데이터 소스에 대한 이전 요청에서 이 클라이언트에 전송된 `DataTable`의 해시입니다. 이는 클라이언트에 동일한 데이터를 두 번 전송하지 않도록 하기 위한 최적화입니다. 이 기능을 사용하는 방법은 아래의 요청 최적화를 참고하세요. `out` - [요청 시 선택사항, 데이터 소스가 처리해야 함] 반환된 데이터의 형식을 설명하는 문자열입니다. 다음 값 중 하나일 수 있습니다. json - [기본값] JSON 응답 문자열입니다 (아래에 설명됨). html - 행과 열이 포함된 기본 HTML 표입니다. 이 속성이 있는 경우 데이터가 포함된 HTML 테이블만 반환해야 합니다. 아래의 응답 형식 섹션에 설명된 대로 디버깅에 유용합니다. csv - 쉼표로 구분된 값. 이 속성을 사용할 경우 반환되는 유일한 항목은 CSV 데이터 문자열입니다. `outFileName` 매개변수를 지정하여 응답 헤더에서 파일의 커스텀 이름을 요청할 수 있습니다. tsv-excel - `csv`와 유사하지만 쉼표 대신 탭을 사용하고 모든 데이터가 utf-16으로 인코딩됩니다. Google 시각화 API를 기반으로 작성된 차트가 요청하는 유일한 데이터 유형은 json입니다. 각 유형에 관한 자세한 내용은 아래의 응답 형식을 참고하세요. `responseHandler` - [요청 시 선택사항, 데이터 소스가 처리해야 함] 클라이언트 페이지에서 응답과 함께 호출되는 JavaScript 처리 함수의 문자열 이름입니다. 요청에 포함되지 않은 경우 값은 'google.visualization.Query.setResponse'입니다. 이 메시지는 응답의 일부로 다시 전송됩니다. 아래 응답 형식에서 방법을 알아보세요. `outFileName` - [요청 시 선택사항, 처리할 데이터 소스의 선택사항] `out:csv` 또는 `out:tsv-excel`를 지정하는 경우 여기에 지정된 파일 이름을 선택적으로 요청할 수 있습니다. 예: `outFileName=results.csv`. 예: `tqx=version:0.6;reqId:1;sig:5277771;out:json`; `responseHandler:myQueryHandler`
tqrt(tqrt)	아니요	아니요	예약됨: 이 매개변수는 무시하세요. 쿼리를 보내는 데 사용된 메서드입니다.

요청에 필수 여부

데이터 소스 처리 대상

설명

아니요

Google 시각화 API 쿼리 언어로 작성된 쿼리로, 반환된 데이터를 필터링, 정렬 또는 조작하는 방법을 지정합니다. 문자열은 따옴표로 묶지 않아도 됩니다.

예: http://www.example.com/mydatasource?tq=select Col1

TQX

아니요

예

표준 또는 맞춤 매개변수의 콜론으로 구분된 키-값 쌍 집합입니다. 각 쌍을 세미콜론으로 구분합니다. 다음은 시각화 프로토콜에서 정의하는 표준 매개변수 목록입니다.

reqId - [요청 시 필요, 데이터 소스에서 처리해야 함] 이 요청의 숫자 식별자입니다. 클라이언트가 응답을 받기 전에 여러 요청을 보내는 경우 데이터 소스가 적절한 요청으로 응답을 식별할 수 있도록 하기 위해 사용됩니다. 이 값을 응답으로 다시 보냅니다.
version - [요청 시 선택사항, 데이터 소스에서 처리해야 함] Google 시각화 프로토콜의 버전 번호입니다. 현재 버전은 0.6입니다. 전송하지 않았다면 최신 버전으로 가정합니다.
sig - [요청 시 선택사항, 처리할 데이터 소스에서 선택사항] 이 데이터 소스에 대한 이전 요청에서 이 클라이언트에 전송된 DataTable의 해시입니다. 이는 클라이언트에 동일한 데이터를 두 번 전송하지 않도록 하기 위한 최적화입니다. 이 기능을 사용하는 방법은 아래의 요청 최적화를 참고하세요.
out - [요청 시 선택사항, 데이터 소스가 처리해야 함] 반환된 데이터의 형식을 설명하는 문자열입니다. 다음 값 중 하나일 수 있습니다.
- json - [기본값] JSON 응답 문자열입니다 (아래에 설명됨).
- html - 행과 열이 포함된 기본 HTML 표입니다. 이 속성이 있는 경우 데이터가 포함된 HTML 테이블만 반환해야 합니다. 아래의 응답 형식 섹션에 설명된 대로 디버깅에 유용합니다.
- csv - 쉼표로 구분된 값. 이 속성을 사용할 경우 반환되는 유일한 항목은 CSV 데이터 문자열입니다. outFileName 매개변수를 지정하여 응답 헤더에서 파일의 커스텀 이름을 요청할 수 있습니다.
- tsv-excel - csv와 유사하지만 쉼표 대신 탭을 사용하고 모든 데이터가 utf-16으로 인코딩됩니다.
Google 시각화 API를 기반으로 작성된 차트가 요청하는 유일한 데이터 유형은 json입니다. 각 유형에 관한 자세한 내용은 아래의 응답 형식을 참고하세요.
responseHandler - [요청 시 선택사항, 데이터 소스가 처리해야 함] 클라이언트 페이지에서 응답과 함께 호출되는 JavaScript 처리 함수의 문자열 이름입니다. 요청에 포함되지 않은 경우 값은 'google.visualization.Query.setResponse'입니다. 이 메시지는 응답의 일부로 다시 전송됩니다. 아래 응답 형식에서 방법을 알아보세요.
outFileName - [요청 시 선택사항, 처리할 데이터 소스의 선택사항] out:csv 또는 out:tsv-excel를 지정하는 경우 여기에 지정된 파일 이름을 선택적으로 요청할 수 있습니다. 예: outFileName=results.csv.

예: tqx=version:0.6;reqId:1;sig:5277771;out:json; responseHandler:myQueryHandler

tqrt(tqrt)

아니요

예약됨: 이 매개변수는 무시하세요. 쿼리를 보내는 데 사용된 메서드입니다.

응답 형식

응답 형식은 예상되는 응답 유형을 지정하는 요청의 out 매개변수에 따라 다릅니다. 각 요청 유형에 응답하는 방법은 다음 섹션을 참조하세요.

JSON - DataTable 생성자에 직접 전달하여 채울 수 있는 자바스크립트 객체의 데이터가 포함된 JSON 응답을 반환합니다. 이는 지금까지 가장 일반적인 요청 유형이며 올바르게 구현하는 것이 가장 중요합니다.
CSV - 브라우저에서 처리할 수 있는 쉼표로 구분된 플랫 값 목록을 반환합니다.
TSV - 브라우저에서 처리할 수 있는 탭으로 구분된 값 목록을 반환합니다.
HTML - 브라우저에서 렌더링할 HTML 테이블을 반환합니다.

Google 시각화 데이터 소스 라이브러리 (자바) 또는 시각화 Python 라이브러리를 사용하여 이러한 출력 형식을 생성할 수 있습니다.

JSON 응답 형식

기본 응답 형식은 요청에 'X-DataSource-Auth' 헤더가 포함된 경우 JSON이고 그렇지 않은 경우 JSONP입니다. Google 차트 클라이언트는 실제로 수정된 버전의 JSON 및 JSONP를 지원합니다. 자바 또는 Python 도우미 라이브러리를 사용하는 경우 적절한 코드가 자동으로 제공됩니다. 직접 응답을 파싱하는 경우 아래의 JSON 수정을 참조하세요.

동일한 도메인 요청을 적용하는 경우 요청에 'X-DataSource-Auth' 헤더가 있는지 확인하고 승인 쿠키를 사용해야 합니다.

이는 Google 시각화 API 메서드 google.visualization.Query.send() 에서 지정하는 유일한 응답 형식입니다. 이 페이지 끝에 있는 예시에서 JSON 요청 및 응답 예시를 확인할 수 있습니다. 자바 또는 Python 도우미 라이브러리를 사용하여 이 응답 문자열을 만들 수 있습니다.

이 응답 형식은 UTF-8로 인코딩된 JSON 객체 (각 속성이 쉼표로 구분된 중괄호 { }로 래핑된 객체)로, 아래 표의 속성을 포함합니다 (데이터는 table 속성에 할당됨). 이 JSON 객체는 요청의 responseHandler 매개변수 값 내에 래핑해야 합니다. 따라서 요청의 responseHandler 값이 'myHandler'라면 다음과 같은 문자열을 반환해야 합니다 (간결성을 위해 속성 하나만 표시됨).

"myHandler({status:ok, ...})"

요청에 responseHandler 값이 포함되지 않은 경우 기본값은 'google.visualization.Query.setResponse'이므로 다음과 같은 문자열을 반환해야 합니다 (간략한 표시를 위해 속성 하나만 표시됨).

"google.visualization.Query.setResponse({status:ok, ...})"

다음은 사용 가능한 응답 객체 멤버입니다.

속성	필수 여부	설명
버전	아니요	Google 시각화 유선 프로토콜 버전 번호를 제공하는 문자열 번호입니다. 지정하지 않으면 클라이언트가 최신 버전을 가정합니다. 예: `version=0.6`
reqId	반환함*	이 클라이언트에 대한 이 요청의 ID를 나타내는 문자열 번호입니다. 이 값이 요청에 포함되어 있으면 같은 값을 반환합니다. 자세한 내용은 요청 섹션의 `reqId` 설명을 참고하세요. * 이 매개변수가 요청에 지정되지 않았으면 응답에서 설정하지 않아도 됩니다.
status	예	이 작업의 성공 또는 실패를 설명하는 문자열입니다. 다음 값 중 하나여야 합니다. `ok` - 요청이 완료되었습니다. 테이블이 `table` 속성에 포함되어야 합니다. `warning` - 완료되었지만 문제가 있습니다. 테이블이 `table` 속성에 포함되어야 합니다. `error` - 문제가 발생했습니다. 이 값을 반환하면 `table`를 반환해서는 안 되며 `errors`을 반환해야 합니다. 예: `status:'warning'`
경고	`status=warning`인 경우에만	하나 이상의 객체의 배열로, 각각 치명적이지 않은 문제를 설명합니다. `status=warning`인 경우 필수이며 그렇지 않은 경우 허용되지 않습니다. 각 객체에는 다음과 같은 문자열 속성이 있습니다 (속성당 하나의 값만 반환). `reason` - [필수] 경고에 대한 한 단어로 된 문자열 설명입니다. 프로토콜은 다음 값을 정의하지만 필요한 경우 사용자가 직접 값을 정의할 수 있습니다(그러나 클라이언트는 특별한 방식으로 커스텀 값을 처리하지 않음). `reason` 값은 하나만 지정할 수 있습니다. `data_truncated` - 사용자가 결과 목록을 잘라낸 쿼리 문자열을 포함했거나 데이터 소스가 어떤 이유로든 전체 결과를 반환하지 않기를 원하기 때문에 반환된 `DataTable`에서 일부 행이 삭제되었습니다. `other` - 지정되지 않은 일반 경고입니다. `message` - [선택사항] 문제를 설명하는 짧은 따옴표로 묶인 문자열로, 알림 상자의 제목으로 사용될 수 있습니다. 사용자에게 표시될 수 있습니다. HTML은 지원되지 않습니다. `detailed_message` - [선택사항] 문제와 가능한 해결 방법을 설명하는 자세한 따옴표로 묶인 문자열 메시지 지원되는 유일한 HTML은 단일 `href` 속성이 있는 `<a>` 요소입니다. 유니코드 인코딩이 지원됩니다. 사용자에게 표시될 수 있습니다. 예: `warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]`
오류	`status=error`인 경우 필수	하나 이상의 객체의 배열로, 각각 오류를 설명합니다. `status=error`이면 필수이며 그렇지 않은 경우에는 허용되지 않습니다. 이 값은 `warnings` 값과 유사합니다. `not_modified` 오류는 오류를 일으킬지라도 실제로는 클라이언트의 오류가 아닙니다. 배열에는 다음과 같은 문자열 멤버가 있습니다 (각 멤버에 대해 하나의 값만 반환). `reason` - [필수] `warnings.reason`와 동일하지만 다음 값이 정의되어 있습니다. `not_modified` - 마지막 요청 이후 데이터가 변경되지 않았습니다. 이로 인해 오류가 발생한 경우 `table` 값이 없어야 합니다. `user_not_authenticated` - 데이터 소스에 인증이 필요한데 아직 완료되지 않았다면 이 값을 지정합니다. 그러면 클라이언트가 `message` 값과 함께 알림을 표시합니다. `unknown_data_source_id` `access_denied` `unsupported_query_operation` `invalid_query` `invalid_request` `internal_error` `not_supported` `illegal_formatting_patterns` `other` - 지정되지 않은 일반 오류입니다. `message` - [선택사항] `warnings.message`와 동일합니다. 참고: 악의적인 사용자가 상세 데이터 문자열을 승인되지 않은 데이터에 액세스하거나 데이터 또는 사이트를 공격하기 위한 수단으로 사용할 수 있습니다. 안전해야 하는 데이터를 저장하거나 사용자 쿼리를 직접 처리하는 경우 공격자에게 정보를 제공할 수 있는 자세한 오류 메시지를 반환하지 않는 것이 좋습니다. 대신 '잘못된 쿼리 문자열'과 같은 일반적인 메시지를 제공하세요. `detailed_message` - [선택사항] `warnings.detailed_message`와 동일합니다. 지나치게 자세한 `message` 정보는 경고를 참조하세요. 예: `status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]`
sig	아니요	표 객체의 해싱된 값입니다. 클라이언트와 데이터 소스 간의 데이터 전송을 최적화하는 데 유용합니다. 원하는 해시 알고리즘을 선택할 수 있습니다. 이 속성을 지원하는 경우 데이터가 반환되지 않으면 클라이언트가 전달한 값을 반환하고 새 데이터가 반환되면 새 해시를 반환해야 합니다. 예: `sig:'5982206968295329967'`
테이블	아니요	데이터가 포함된 JavaScript 리터럴 표기법의 `DataTable` 객체 이 객체의 형식에 대한 자세한 내용은 연결된 참조 섹션을 확인하세요. 다음은 간단한 데이터 테이블의 예입니다. {cols:[{id:'Col1',label:'',type:'number'}], rows:[{c:[{v:1.0,f:'1'}]}, {c:[{v:2.0,f:'2'}]}, {c:[{v:3.0,f:'3'}]}, {c:[{v:1.0,f:'1'}]} ] } `table` 속성은 `status=ok` 또는 `status=warning`인 경우에만 있어야 합니다. 데이터를 반환하지 않는 경우에는 이 속성을 포함하지 마세요. 즉, 빈 문자열 값이 있는 속성을 다시 전달하지 마세요. 예: 아래의 예를 참고하세요.

엄격한 JSON 필요

Google의 도우미 라이브러리와 Google로 전송되는 모든 쿼리는 엄격한 JSON/JSONP를 반환합니다. 반환된 코드를 직접 파싱하지 않는 경우에는 이 방식이 중요하지 않습니다. 그렇다면 JSON.parse()를 사용하여 JSON 문자열을 자바스크립트 객체로 변환할 수 있습니다. API에서 JSON을 처리하는 방식의 한 가지 차이점은 JSON이 JavaScript 날짜 값 (예: 'new Date(2008,1,28,0,31,26)'을 지원하지 않더라도) Date(year, month, day[,hour, minute, second[, millisecond]]) 형식의 날짜 문자열로 유효한 JSON 표현을 지원한다는 것입니다. 여기서 일 후의 모든 것은 선택사항이며 월은 0부터 시작합니다.

JSON 응답 최적화

클라이언트가 두 개의 요청을 하고 요청 간에 데이터가 변경되지 않은 경우 데이터를 재전송하지 않는 것이 좋습니다. 이렇게 하면 대역폭이 낭비됩니다. 요청을 더 효율적으로 만들기 위해 프로토콜은 클라이언트의 데이터를 캐시하고 마지막 요청 이후 데이터가 변경되지 않은 경우 응답에서 신호를 전송하는 기능을 지원합니다. 계산 방법은 다음과 같습니다.

클라이언트가 데이터 소스에 요청을 보냅니다.
데이터 소스는 DataTable와 DataTable 객체의 해시를 생성하고 두 가지를 응답으로 반환합니다 (해시는 tqx.sig 매개변수에 반환됨). Google 시각화 API 클라이언트는 DataTable 및 sig 값을 캐시합니다.
클라이언트는 캐시된 tqx.sig 값을 포함하여 다른 데이터 요청을 보냅니다.
데이터 소스는 다음 두 가지 방법 중 하나로 응답할 수 있습니다.
- 데이터가 이전 요청에서 변경되었다면 데이터 소스는 새로운 DataTable 및 새 sig 값 해시를 다시 보냅니다.
- 데이터가 이전 요청에서 변경되지 않았다면 데이터 소스는 status=error, reason=not_modified, sig=old_sig_value를 반환합니다.
두 경우 모두 차트를 호스팅하는 페이지가 성공적인 응답을 받고 QueryResponse.getDataTable()를 호출하여 DataTable를 가져올 수 있습니다. 데이터가 동일하면 테이블의 캐시된 버전이 됩니다.

이 방법은 Google 시각화 API를 기반으로 작성된 차트의 JSON 요청에만 적용됩니다.

CSV 응답 형식

요청에서 out:csv을 지정하면 응답에 메타데이터는 포함되지 않고 단순히 데이터의 CSV 표현만 포함됩니다. CSV 테이블은 일반적으로 쉼표로 구분된 목록이며, 여기서 각 데이터 행은 쉼표로 구분된 값 목록이며 UNIX 줄바꿈 문자 (\n)로 끝납니다. 각 열의 셀 값의 유형은 동일해야 합니다. 첫 번째 행은 열 라벨입니다. 다음은 3행 3열 테이블의 예입니다.

A, B, C
1.0, "yes", true
2.0, "no", false
3.0, "maybe", true

CSV 형식은 이 프로토콜로 지정되지 않습니다. 데이터 소스가 CSV 형식을 정의합니다. 그러나 일반적인 형식은 공백 없이 쉼표로 구분된 값의 집합과 모든 행의 끝에 줄바꿈(\n)을 사용하는 것입니다. 브라우저가 CSV 문자열 응답을 수신하면 사용자에게 문자열을 여는 데 사용할 애플리케이션을 물어보거나 단순히 화면에 렌더링할 수 있습니다. 자바 및 Python 오픈소스 라이브러리는 DataTable을 CSV 문자열로 변환하는 방법을 제공합니다.

요청에 tqx 매개변수의 outFileName 구성원이 포함되어 있으면 지정된 파일 이름을 응답 헤더에 포함해야 합니다.

google.visualization.Query 객체는 CSV 응답 요청을 지원하지 않습니다. 클라이언트가 CSV를 요청하려는 경우 페이지에 시각화 툴바 가젯을 삽입하거나, 커스텀 코드를 사용하여 요청을 만들 수 있습니다. 또는 다음 요청 URL과 같이 tqx의 out:csv 속성을 명시적으로 설정하는 링크를 제공할 수도 있습니다.

요청

http://www.example.com/mydatasource?tqx=reqId:1;out:csv

응답

Label 1,Label2\n1,a\n2,b\n3,c\n4,d

TSV 응답 형식

요청이 out:tsv-excel를 지정하면 응답에는 메타데이터가 포함되지 않고 utf-16으로 인코딩된 탭으로 구분된 데이터 표현만 포함됩니다. 요청에 tqx 매개변수의 outFileName 구성원이 포함되어 있으면 지정된 파일 이름을 응답 헤더에 포함해야 합니다.

HTML 응답 형식

요청이 out:html을 지정하는 경우 응답은 데이터가 포함된 HTML 테이블을 정의하는 HTML 페이지여야 합니다. 브라우저가 결과를 읽을 수 있는 형식으로 직접 렌더링할 수 있으므로 이는 코드 디버깅에 유용합니다. google.visualization.Query 객체를 사용하여 HTML 응답에 대한 쿼리를 보낼 수 없습니다. 커스텀 코드를 사용하거나 브라우저에 다음과 유사한 URL을 입력하여 HTML 응답에 대해 쿼리를 수행해야 합니다.

요청

http://www.example.com/mydatasource?tqx=reqId:1;out:html

응답

<html><body><table border='1' cellpadding='2' cellspacing='0'><tr style='font-weight: bold; background-color: #aaa;'><td>label 1</td><td>label 2</td></tr><tr bgcolor='#f0f0f0'><td align='right'>1</td><td>a</td></tr><tr bgcolor='#ffffff'><td align='right'>2</td><td>b</td></tr><tr bgcolor='#f0f0f0'><td align='right'>3</td><td>c</td></tr><tr bgcolor='#ffffff'><td align='right'>4</td><td>d</td></tr></table></body></html>

예

다음은 요청과 응답의 몇 가지 예입니다. 요청은 URL 이스케이프 처리되지 않았습니다. 일반적으로 브라우저 또는 google.visualization.Query 객체에서 실행됩니다.

간단한 요청: 3열, 4행 테이블로 기본 정보를 반환합니다.

Request:
http://www.example.com/mydatasource

Response
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'5982206968295329967',table:{cols:[{id:'Col1',label:'',type:'number'},{id:'Col2',label:'',type:'number'},{id:'Col3',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]},{c:[{v:2.0,f:'2'},{v:3.0,f:'3'},{v:4.0,f:'4'}]},{c:[{v:3.0,f:'3'},{v:4.0,f:'4'},{v:5.0,f:'5'}]},{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]}]}});

응답 핸들러를 사용하는 간단한 요청: 데이터 유형이 서로 다른 3개 열, 3개 행 테이블을 반환합니다.

Request:
http://www.example.com/mydatasource?tqx=responseHandler:myHandlerFunction

Response
myHandlerFunction({version:'0.6',reqId:'0',status:'ok',sig:'4641982796834063168',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]},{c:[{v:'b'},{v:2.0,f:'2'},{v:new Date(2008,2,30,0,31,26),f:'3/30/08 12:31 AM'}]},{c:[{v:'c'},{v:3.0,f:'3'},{v:new Date(2008,3,30,0,31,26),f:'4/30/08 12:31 AM'}]}]}});

간단한 쿼리 문자열로 쿼리: 단일 열을 요청하면 행이 4개인 단일 열을 반환합니다.

Request:
http://www.example.com/mydatasource?tq=select Col1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'6099996038638149313',table:{cols:[{id:'Col1',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'}]},{c:[{v:2.0,f:'2'}]},{c:[{v:3.0,f:'3'}]},{c:[{v:1.0,f:'1'}]}]}});

데이터 수정되지 않음 오류: not_modified 오류의 예

Request:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]});

데이터 잘림 경고: data_truncated 경고의 예입니다. 요청은 여전히 데이터를 반환합니다.

Request:
http://www.example.com/mydatasource?tq=limit 1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'warning',warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}],sig:'1928724788649668508',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]}]}});

액세스 거부 오류: access_denied 오류의 예입니다.

Request:
http://www.example.com/mydatasource

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'access_denied',message:'Access denied',detailed_message:'Access Denied'}]});

잘못된 쿼리 문자열: 잘못된 쿼리 문자열이 포함된 요청의 예입니다. 세부 메시지는 실제 오류 메시지가 아닌 일반적인 메시지입니다.

Request:
http://www.example.com/mydatasource?tq=select A

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'invalid_query',message:'Invalid query',detailed_message:'Bad query string.'}]});

개발 도구

Java 데이터 소스 라이브러리 (Google 제공) - 요청 및 응답을 처리하고, 제공된 데이터로 응답 테이블을 만들고, Google 차트 도구의 SQL 쿼리 언어를 구현합니다.
Python 데이터 소스 라이브러리 (Google 제공) - 응답 구문을 생성하는 응답 테이블을 만듭니다. 요청 파싱 또는 Google Chart Tools SQL 쿼리 언어 구현을 처리하지 않습니다.
MC-Google_Visualization (타사) - PDO를 사용하여 MySQL, SQLite, PostgreSQL 데이터베이스 엔진용 차트 도구 데이터 소스를 구현하는 데 사용할 수 있는 PHP 서버 측 라이브러리입니다.
bortosky-google-visualization (타사) - .NET 사용자용 Google 시각화 API 데이터 표를 만드는 도우미 라이브러리입니다.
GV Streamer (서드 파티) - GV Streamer는 다양한 소스의 데이터를 Google 차트에 대한 유효한 쿼리 응답으로 변환할 수 있는 서버 측 도구입니다. GV Streamer는 여러 언어 (예: PHP, Java, .NET)와 여러 원시 데이터 소스(예: MySql)를 지원합니다.
TracGViz(타사) - TracGViz는 무료 오픈소스 도구로, Trac에서 차트 가젯을 사용할 수 있도록 구성요소를 제공하고, Trac에서 Google 차트 도구 데이터 소스로 관리하는 데이터를 구현합니다.
vis-table (타사) - PHP로 Google Chart Tools 데이터 소스를 구현하는 라이브러리입니다. 세 가지 주요 부분으로 구성됩니다. 데이터 테이블 구현 자체, 쿼리 언어 파서 및 형식 지정 도구
Oracle PL/SQL의 Google 데이터 소스 구현 (타사) - Oracle이 데이터베이스에서 직접 서버 데이터 소스를 사용할 수 있게 해주는 Oracle PL/SQL 패키지입니다. 따라서 기본적으로 모든 Oracle 쿼리를 Google Chart Tools 데이터 소스로 사용할 수 있습니다 (패키지가 데이터와 함께 JSON 파일을 반환함). Google 쿼리 언어를 거의 완전히 지원합니다.