목차
소개
이 문서는 Books API와 상호작용할 수 있는 애플리케이션을 작성하려는 개발자를 대상으로 합니다. Google 도서의 사명은 전 세계의 도서 콘텐츠를 디지털화하여 웹에서 더 쉽게 검색할 수 있게 하는 것입니다. Books API를 사용하면 콘텐츠를 검색하고 액세스할 수 있을 뿐만 아니라 콘텐츠 맞춤설정을 만들고 볼 수 있습니다.
Google 도서 개념에 익숙하지 않으면 코딩을 시작하기 전에 시작하기를 읽어야 합니다.
요청 승인 및 애플리케이션 식별
애플리케이션에서 Books API에 전송하는 모든 요청은 Google에 애플리케이션을 식별해야 합니다. 애플리케이션을 식별하는 방법에는 OAuth 2.0 토큰을 사용하거나(이 토큰은 요청도 승인함) 애플리케이션의 API 키를 사용하는 두 가지 방법이 있습니다. 다음과 같은 방법으로 사용할 옵션을 결정합니다.
- 요청에 승인이 필요한 경우 (예: 개인의 비공개 데이터 요청) 애플리케이션은 요청과 함께 OAuth 2.0 토큰을 제공해야 합니다. 애플리케이션에서 API 키를 제공할 수도 있지만 필수는 아닙니다.
- 요청에 승인이 필요하지 않은 경우(예: 공개 데이터 요청) 애플리케이션은 API 키 또는 OAuth 2.0 토큰 중 하나 또는 둘 다를 편의에 따라 제공해야 합니다.
승인 프로토콜 정보
요청을 승인하려면 애플리케이션에서 OAuth 2.0을 사용해야 합니다. 다른 승인 프로토콜은 지원되지 않습니다. 애플리케이션에서 Google 계정으로 로그인을 사용하는 경우, 승인의 일부 절차는 자동으로 처리됩니다.
OAuth 2.0을 사용하여 요청 승인하기
Books API에 대한 비공개 사용자 데이터 요청은 인증된 사용자의 승인을 받아야 합니다.
OAuth 2.0의 세부적인 승인 절차('흐름')는 제작 중인 애플리케이션 종류에 따라 약간씩 다릅니다. 다음의 일반적인 과정은 모든 애플리케이션 유형에 적용됩니다.
- 애플리케이션을 만들 때 Google API 콘솔을 사용하여 애플리케이션을 등록합니다. 이렇게 하면 Google에서 클라이언트 ID 및 클라이언트 보안 비밀과 같이 나중에 필요한 정보를 제공합니다.
- Google API 콘솔에서 Books API를 활성화합니다. API 콘솔의 목록에 이 API가 없다면 이 단계를 건너뜁니다.
- 애플리케이션에서 사용자 데이터에 액세스해야 하는 경우 Google에 특정 액세스 범위를 요청합니다.
- Google에서 사용자에게 애플리케이션이 일부 데이터를 요청하도록 승인할 것인지 물어보는 동의 화면을 표시합니다.
- 사용자가 승인하면 Google에서 애플리케이션에 제한 시간이 있는 액세스 토큰을 제공합니다.
- 애플리케이션에서 액세스 토큰을 첨부하여 사용자 데이터를 요청합니다.
- Google에서 요청과 토큰이 유효하다고 판단하면 요청된 데이터를 반환합니다.
일부 흐름에는 새로운 액세스 토큰을 얻기 위해 갱신 토큰을 사용하는 등의 추가 단계가 포함됩니다. 다양한 유형의 애플리케이션에 적용되는 흐름을 자세히 알아보려면 Google의 OAuth 2.0 문서를 참조하세요.
다음은 Books API의 OAuth 2.0 범위 정보입니다.
https://www.googleapis.com/auth/books
OAuth 2.0을 사용하여 액세스를 요청하려면 애플리케이션에 범위 정보와 함께 애플리케이션 등록 시 Google에서 제공하는 정보(예: 클라이언트 ID, 클라이언트 보안 비밀)가 필요합니다.
팁: Google API 클라이언트 라이브러리가 사용자를 대신하여 일부 승인 과정을 처리할 수 있습니다. 여러 가지 프로그래밍 언어로 제공되므로 자세한 내용은 라이브러리 및 샘플 페이지를 참조하세요.
API 키 획득 및 사용
Books API에 대한 공개 데이터 요청에는 식별자가 수반되어야 합니다. 식별자는 API 키 또는 액세스 토큰일 수 있습니다.
API 키를 획득하려면 다음 안내를 따르세요.
- API 콘솔에서 사용자 인증 정보 페이지를 엽니다.
-
이 API는 두 가지 유형의 사용자 인증 정보를 지원합니다.
프로젝트에 적합한 사용자 인증 정보를 만듭니다.
-
OAuth 2.0: 애플리케이션에서 비공개 사용자 데이터를 요청할 때마다 요청과 함께 OAuth 2.0 토큰을 보내야 합니다. 애플리케이션은 먼저 토큰을 획득하기 위해 클라이언트 ID나 클라이언트 보안 비밀번호를 보냅니다. 웹 애플리케이션, 서비스 계정, 설치된 애플리케이션의 OAuth 2.0 사용자 인증 정보를 생성할 수 있습니다.
자세한 내용은 OAuth 2.0 문서를 참조하세요.
-
API 키: OAuth 2.0 토큰을 제공하지 않는 요청은 API 키를 전송해야 합니다. 키는 프로젝트를 식별하고 API 액세스, 할당량, 보고서를 제공합니다.
API는 여러 유형의 API 키 제한 사항을 지원합니다. 필요한 API 키가 아직 없는 경우 사용자 인증 정보 만들기 > API 키를 클릭하여 Console에서 API 키를 만듭니다. 프로덕션 단계에서 사용하기 전에 키 제한을 클릭하고 제한사항 중 하나를 선택하여 키를 제한할 수 있습니다.
-
API 키를 안전하게 보호하려면 API 키를 안전하게 사용하기 위한 권장사항을 따르세요.
API 키가 있으면 애플리케이션은 모든 요청 URL에 쿼리 매개변수 key=yourAPIKey를 추가할 수 있습니다.
API 키는 URL에 포함하기에 안전합니다. 인코딩이 전혀 필요하지 않습니다.
Google 도서 ID
특정 API 메서드 호출로 ID 필드를 지정해야 합니다. Google 도서에서 사용되는 ID에는 세 가지 유형이 있습니다.
- 볼륨 ID - Google 도서에서 알고 있는 각 볼륨에 제공되는 고유한 문자열입니다. 볼륨 ID의 예는
_LettPDhwR0C입니다. 볼륨 리소스를 반환하는 요청을 실행하여 API를 사용하여 볼륨 ID를 가져올 수 있습니다. 볼륨 ID는id필드에서 찾을 수 있습니다. - 서가 ID - 사용자 라이브러리의 서가에 제공된 숫자 값입니다. Google에서는 다음 ID가 있는 모든 사용자에게 사전 정의된 서가를 제공합니다.
- 즐겨찾기: 0
- 구매일: 1
- 읽을거리: 2
- 지금 읽기: 3
- 읽은 시간: 4
- 검토됨: 5
- 최근에 본 항목: 6
- 내 eBook: 7
- 추천 도서: 8 사용자에게 추천할 사항이 없으면 이 서가는 존재하지 않습니다.
id필드에서 찾을 수 있습니다. - 사용자 ID - 각 사용자에게 할당된 고유한 숫자 값입니다. 이 값은 다른 Google 서비스에서 사용되는 ID 값과 반드시 동일하지는 않습니다. 현재 사용자 ID를 검색하는 유일한 방법은 인증된 요청으로 검색된 서가 리소스의 selfLink에서 사용자 ID를 추출하는 것입니다. 도서 사이트에서도 사용자 ID를 확인할 수 있습니다. 사용자는 API 또는 도서 사이트를 통해 다른 사용자의 사용자 ID를 얻을 수 없습니다. 다른 사용자는 이메일 등을 통해 이 정보를 명시적으로 공유해야 합니다.
Google 도서 사이트의 ID
Books API에서 사용하는 ID는 Google 도서 사이트에서 사용되는 ID와 동일합니다.
- 볼륨 ID
사이트에서 특정 볼륨을 볼 때
idURL 매개변수에서 볼륨 ID를 찾을 수 있습니다. 예를 들면 다음과 같습니다.https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- 서가 ID
사이트에서 특정 서가를 볼 때
as_collURL 매개변수에서 서가 ID를 찾을 수 있습니다. 예를 들면 다음과 같습니다.https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
- 사용자 ID
사이트에서 라이브러리를 볼 때
uidURL 매개변수에서 사용자 ID를 찾을 수 있습니다. 예를 들면 다음과 같습니다.https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
사용자 위치 설정
Google 도서는 최종 사용자의 위치와 관련된 저작권, 계약 및 기타 법적 제한을 준수합니다. 따라서 일부 사용자는 특정 국가의 도서 콘텐츠에 액세스하지 못할 수도 있습니다. 예를 들어 특정 도서는 미국에서만 '미리보기'가 가능하므로 다른 국가의 사용자에게는 이러한 미리보기 링크는 생략합니다. 따라서 API 결과는 서버 또는 클라이언트 애플리케이션의 IP 주소에 따라 제한됩니다.
볼륨 작업
검색하기
다음 URI로 HTTP GET 요청을 전송하여 볼륨 검색을 수행할 수 있습니다.
https://www.googleapis.com/books/v1/volumes?q=search+terms
이 요청에는 단일 필수 매개변수가 있습니다.
q- 이 텍스트 문자열이 포함된 볼륨을 검색합니다. 특정 필드에서 검색을 위해 검색어에 지정할 수 있는 다음과 같은 특수 키워드가 있습니다.intitle:제목에서 이 키워드 뒤에 오는 텍스트가 있는 결과를 반환합니다.inauthor:작성자에서 이 키워드 뒤에 오는 텍스트가 있는 결과를 반환합니다.inpublisher:게시자에서 이 키워드 뒤에 오는 텍스트가 발견된 결과를 반환합니다.subject:이 키워드 다음에 오는 텍스트가 볼륨 카테고리 목록에 나열된 결과를 반환합니다.isbn:이 키워드 뒤에 오는 텍스트가 ISBN 번호인 결과를 반환합니다.lccn:이 키워드 다음에 오는 텍스트가 미국 의회도서관 제어 번호인 결과를 반환합니다.oclc:이 키워드 다음에 오는 텍스트가 온라인 컴퓨터 도서관 센터 번호인 결과를 반환합니다.
요청
다음은 Daniel Keyes의 'Flowers for Algernon'을 검색하는 예입니다.
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
참고: 검색은 인증이 필요하지 않으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다. 그러나 인증으로 호출하는 경우 각 볼륨에는 구매 상태와 같은 사용자별 정보가 포함됩니다.
응답
요청이 성공하면 서버에서 200 OK HTTP 상태 코드와 볼륨 결과를 응답으로 반환합니다.
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "_ojXNuzgHRcC",
"etag": "OTD2tB19qn4",
"selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Vijaya Khisty Bodach"
],
...
},
{
"kind": "books#volume",
"id": "RJxWIQOvoZUC",
"etag": "NsxMT6kCCVs",
"selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Gail Saunders-Smith"
],
...
},
{
"kind": "books#volume",
"id": "zaRoX10_UsMC",
"etag": "pm1sLMgKfMA",
"selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Paul McEvoy"
],
...
},
"totalItems": 3
}
선택적 쿼리 매개변수
볼륨 검색을 수행할 때 표준 쿼리 매개변수 외에도 다음 쿼리 매개변수를 사용할 수 있습니다.
다운로드 형식
download 매개변수를 사용하면 를 epub 값으로 설정하여 반환되는 결과를 epub의 사용 가능한 다운로드 형식이 있는 볼륨으로 제한합니다.
다음 예는 eBook 다운로드가 가능한 책을 검색합니다.
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
필터링
filter 매개변수를 사용하면 다음 값 중 하나로 설정하여 반환되는 결과를 더 제한할 수 있습니다.
partial- 텍스트의 일부분을 미리 볼 수 있는 결과를 반환합니다.full- 모든 텍스트를 볼 수 있는 결과만 반환합니다.free-ebooks- 무료 Google eBook 검색결과만 반환합니다.paid-ebooks- 가격이 있는 Google eBook 검색결과만 반환합니다.ebooks- Google eBook(유료 또는 무료) 결과만 반환합니다. eBook이 아닌 콘텐츠의 예로는 일부 미리보기로 제공되며 판매용으로는 사용할 수 없는 게시자 콘텐츠 또는 잡지가 있습니다.
다음 예에서는 무료 eBook으로 제공되는 결과로 검색결과를 제한합니다.
GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
페이지로 나누기
요청의 매개변수에 두 값을 지정하여 볼륨 목록을 페이지로 나눌 수 있습니다.
startIndex- 컬렉션에서 시작할 위치입니다. 첫 번째 항목의 색인은 0입니다.maxResults- 반환할 최대 결과 수입니다. 기본값은 10이고 최대 허용 값은 40입니다.
프린트 유형
printType 매개변수를 사용하면 다음 값 중 하나로 설정하여 반환된 결과를 특정 인쇄 또는 간행물 유형으로 제한할 수 있습니다.
all- 인쇄 유형을 기준으로 제한하지 않습니다 (기본값).books- 도서 결과만 반환합니다.magazines- 잡지인 결과를 반환합니다.
다음 예는 검색 결과를 잡지로 제한합니다.
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
투영
projection 매개변수를 다음 값 중 하나와 함께 사용하여 반환할 사전 정의된 볼륨 필드 집합을 지정할 수 있습니다.
full- 모든 볼륨 필드를 반환합니다.lite- 특정 필드만 반환합니다. 포함된 필드를 확인하려면 볼륨 참조에서 이중 별표로 표시된 필드 설명을 참조하세요.
다음 예는 제한된 양의 정보가 포함된 검색 결과를 반환합니다.
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
정렬
기본적으로 볼륨 검색을 요청하면 maxResults 결과가 반환됩니다. 여기서 maxResults는 페이지로 나누기에 사용된 매개변수이며 검색어와 관련된 순서대로 정렬됩니다.
orderBy 매개변수를 다음 값 중 하나로 설정하여 순서를 변경할 수 있습니다.
relevance- 검색어의 관련성 순으로 결과를 반환합니다 (기본값).newest- 게시된 시간 순으로 결과를 반환합니다.
다음 예는 결과를 게시 날짜순으로 나열합니다(최신순에서 오래된 날짜순).
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
특정 볼륨 검색
볼륨 리소스 URI에 HTTP GET 요청을 전송하여 특정 볼륨의 정보를 검색할 수 있습니다.
https://www.googleapis.com/books/v1/volumes/volumeId
volumeId 경로 매개변수를 검색할 볼륨의 ID로 바꿉니다. 볼륨 ID에 관한 자세한 내용은 Google 도서 ID 섹션을 참고하세요.
요청
다음은 단일 볼륨을 가져오는 GET 요청의 예시입니다.
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
참고: 볼륨 정보를 가져올 때는 인증이 필요하지 않으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다. 그러나 호출이 인증으로 이루어지는 경우 볼륨에는 구매 상태와 같은 사용자별 정보가 포함됩니다.
응답
요청이 성공하면 서버가 200 OK HTTP 상태 코드와 요청된 볼륨 리소스로 응답합니다.
200 OK
{
"kind": "books#volume",
"id": "zyTCAlFPjgYC",
"etag": "f0zKg75Mx/I",
"selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
"volumeInfo": {
"title": "The Google story",
"authors": [
"David A. Vise",
"Mark Malseed"
],
"publisher": "Random House Digital, Inc.",
"publishedDate": "2005-11-15",
"description": "\"Here is the story behind one of the most remarkable Internet
successes of our time. Based on scrupulous research and extraordinary access
to Google, ...",
"industryIdentifiers": [
{
"type": "ISBN_10",
"identifier": "055380457X"
},
{
"type": "ISBN_13",
"identifier": "9780553804577"
}
],
"pageCount": 207,
"dimensions": {
"height": "24.00 cm",
"width": "16.03 cm",
"thickness": "2.74 cm"
},
"printType": "BOOK",
"mainCategory": "Business & Economics / Entrepreneurship",
"categories": [
"Browsers (Computer programs)",
...
],
"averageRating": 3.5,
"ratingsCount": 136,
"contentVersion": "1.1.0.0.preview.2",
"imageLinks": {
"smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
"thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
"small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
"medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
"large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
"extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
},
"language": "en",
"infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
"canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
},
"saleInfo": {
"country": "US",
"saleability": "FOR_SALE",
"isEbook": true,
"listPrice": {
"amount": 11.99,
"currencyCode": "USD"
},
"retailPrice": {
"amount": 11.99,
"currencyCode": "USD"
},
"buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
},
"accessInfo": {
"country": "US",
"viewability": "PARTIAL",
"embeddable": true,
"publicDomain": false,
"textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
"epub": {
"isAvailable": true,
"acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
},
"pdf": {
"isAvailable": false
},
"accessViewStatus": "SAMPLE"
}
}
액세스 정보
accessInfo 섹션은 특히 eBook에서 사용할 수 있는 기능을 결정하는 데 유용합니다. epub는 맞춤 텍스트 형식의 eBook으로, epub 섹션에는 이 유형의 eBook을 사용할 수 있는지 나타내는 isAvailable 속성이 있습니다.
책의 샘플이 있거나 사용자가 책을 구매했거나
사용자 위치의 공개 도메인이어서 책을 읽을 수 있는 경우 다운로드 링크가
있습니다. Google 도서의 pdf은 eBook의 스캔 페이지 버전(예: 사용 가능 여부 및 다운로드 링크)이 유사한지를 나타냅니다. eReader 및 스마트폰에서는 스캔된 페이지를 읽기 어려울 수 있으므로 epub 파일을 사용하는 것이 좋습니다.
accessInfo 섹션이 없으면 해당 볼륨을 Google eBook으로 사용할 수 없습니다.
선택적 쿼리 매개변수
특정 볼륨을 검색할 때 표준 쿼리 매개변수 외에도 다음 쿼리 매개변수를 사용할 수 있습니다.
투영
projection 매개변수를 다음 값 중 하나와 함께 사용하여 반환할 사전 정의된 볼륨 필드 집합을 지정할 수 있습니다.
full- 모든 볼륨 필드를 반환합니다.lite- 특정 필드만 반환합니다. 포함된 필드를 확인하려면 볼륨 참조에서 이중 별표로 표시된 필드 설명을 참조하세요.
다음 예시는 단일 볼륨에 대해 제한된 볼륨 정보를 반환합니다.
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
서가 사용하기
사용자의 공개 서가 목록 검색
다음 형식으로 URI에 HTTP GET 요청을 전송하여 사용자의 공개 서가 목록을 검색할 수 있습니다.
https://www.googleapis.com/books/v1/users/userId/bookshelves
userId 경로 매개변수를 서가를 가져오려는 사용자의 ID로 바꿉니다. 사용자 ID에 관한 자세한 내용은 Google 도서 ID 섹션을 참고하세요.
요청
예를 들면 다음과 같습니다.
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
공개 서가 관련 정보를 검색하기 위해 사용자를 인증할 필요가 없으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다.
응답
요청이 성공하면 서버에서 200 OK HTTP 상태 코드와 서가 목록을 반환합니다.
200 OK
{
"kind": "books#bookshelves",
"items": [
{
...
},
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"description": "",
"access": "PUBLIC",
"updated": "2011-02-02T20:34:20.146Z",
"created": "2011-02-02T20:34:20.146Z",
"volumeCount": 2,
"volumesLastUpdated": "2011-02-02T20:34:20.110Z"
},
...
]
}
선택적 쿼리 매개변수
사용자의 공개 서가 목록을 가져올 때 표준 쿼리 매개변수를 사용할 수 있습니다.
특정 공개 서가 검색
다음 형식으로 URI에 HTTP GET 요청을 전송하여 특정 공개 서가를 검색할 수 있습니다.
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
userId 및 shelf 경로 매개변수를 검색할 사용자와 서가를 지정하는 ID로 바꿉니다. 자세한 내용은 Google 도서 ID 섹션을 참고하세요.
요청
예를 들면 다음과 같습니다.
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
공개 서가 관련 정보를 검색하기 위해 사용자를 인증할 필요가 없으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다.
응답
요청이 성공하면 서버는 200 OK HTTP 상태 코드와 서가 리소스를 응답으로 반환합니다.
200 OK
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"description": "",
"access": "PUBLIC",
"updated": "2011-02-02T20:34:20.146Z",
"created": "2011-02-02T20:34:20.146Z",
"volumeCount": 2,
"volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}
선택적 쿼리 매개변수
특정 공개 서가를 검색할 때 표준 쿼리 매개변수를 사용할 수 있습니다.
공개 서가의 볼륨 목록 검색
다음 형식으로 URI에 HTTP GET 요청을 전송하여 사용자의 공개 서가의 볼륨 목록을 검색할 수 있습니다.
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
요청
예를 들면 다음과 같습니다.
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
userId 및 shelf 경로 매개변수를 검색할 사용자와 서가를 지정하는 ID로 바꿉니다. 자세한 내용은 Google 도서 ID 섹션을 참고하세요.
공개 서가 관련 정보를 검색하기 위해 사용자를 인증할 필요가 없으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다.
응답
요청이 성공하면 서버에서 200 OK HTTP 상태 코드와 사용자의 서가 목록을 반환합니다.
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "AZ5J6B1-4BoC",
"etag": "kIzQA7IUObk",
"selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
"volumeInfo": {
"title": "The Girl Who Kicked the Hornet's Nest",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2010-05-25",
...
},
{
"kind": "books#volume",
"id": "UvK1Slvkz3MC",
"etag": "otKmdbRgdFQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
"volumeInfo": {
"title": "The Girl who Played with Fire",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2009-07-28",
...
},
{
"kind": "books#volume",
"id": "OBM3AAAAIAAJ",
"etag": "xb47kTr8HsQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
"volumeInfo": {
"title": "The Sign of Four",
"authors": [
"Sir Arthur Conan Doyle"
],
"publishedDate": "1890",
...
}
],
"totalItems": 3
}
선택적 쿼리 매개변수
공개 서가의 볼륨 목록을 가져올 때 표준 쿼리 매개변수 외에도 다음 쿼리 매개변수를 사용할 수 있습니다.
페이지로 나누기
요청의 매개변수에 두 값을 지정하여 볼륨 목록을 페이지로 나눌 수 있습니다.
startIndex- 컬렉션에서 시작할 위치입니다. 첫 번째 항목의 색인은 0입니다.maxResults- 반환할 최대 결과 수입니다. 기본값은 10이고 최대 허용 값은 40입니다.
'내 라이브러리'의 서가 관리하기
모든 '내 라이브러리' 요청은 인증된 사용자의 데이터에 적용됩니다.
내 서가 목록 가져오기
다음 형식으로 URI에 HTTP GET 요청을 전송하여 인증된 사용자의 모든 서가 목록을 검색할 수 있습니다.
https://www.googleapis.com/books/v1/mylibrary/bookshelves
요청
예를 들면 다음과 같습니다.
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
참고: '내 라이브러리' 서가 목록을 검색하려면 사용자를 인증해야 합니다. 따라서 GET 요청과 함께 Authorization HTTP 헤더를 제공해야 합니다.
응답
요청이 성공하면 서버에서 200 OK HTTP 상태 코드와 현재 인증된 사용자의 모든 서가 목록을 응답으로 반환합니다.
200 OK
{
"kind": "books#bookshelves",
"items": [
{
"kind": "books#bookshelf",
"id": 0,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
"title": "Favorites",
"access": "PRIVATE",
"updated": "2011-04-22T04:03:15.416Z",
"created": "2011-04-22T04:03:15.416Z",
"volumeCount": 0,
"volumesLastUpdated": "2011-04-22T04:03:17.000Z"
},
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"access": "PUBLIC",
"updated": "2010-11-11T19:44:22.377Z",
"created": "2010-11-11T19:44:22.377Z",
"volumeCount": 1,
"volumesLastUpdated": "2010-11-11T19:44:22.341Z"
}
]
}
선택적 쿼리 매개변수
인증된 사용자의 서가 목록을 가져올 때 표준 쿼리 매개변수를 사용할 수 있습니다.
서가의 볼륨 목록 가져오기
다음 형식으로 URI에 HTTP GET 요청을 전송하여 인증된 사용자의 서가에 있는 볼륨 목록을 검색할 수 있습니다.
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.
요청
예를 들면 다음과 같습니다.
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
참고: 'My Library' 볼륨의 목록을 가져오려면 사용자를 인증해야 합니다. 따라서 GET 요청과 함께 Authorization HTTP 헤더를 제공해야 합니다.
응답
요청이 성공하면 서버가 200 OK HTTP 상태 코드와 서가 볼륨 목록을 응답으로 반환합니다.
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "AZ5J6B1-4BoC",
"etag": "kIzQA7IUObk",
"selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
"volumeInfo": {
"title": "The Girl Who Kicked the Hornet's Nest",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2010-05-25",
...
},
{
"kind": "books#volume",
"id": "UvK1Slvkz3MC",
"etag": "otKmdbRgdFQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
"volumeInfo": {
"title": "The Girl who Played with Fire",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2009-07-28",
...
},
{
"kind": "books#volume",
"id": "OBM3AAAAIAAJ",
"etag": "xb47kTr8HsQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
"volumeInfo": {
"title": "The Sign of Four",
"authors": [
"Sir Arthur Conan Doyle"
],
"publishedDate": "1890",
...
}
],
"totalItems": 3
}
선택적 쿼리 매개변수
인증된 사용자의 서가 중 하나에서 볼륨 목록을 가져올 때 표준 쿼리 매개변수 외에도 다음 쿼리 매개변수를 사용할 수 있습니다.
페이지로 나누기
요청의 매개변수에 두 값을 지정하여 볼륨 목록을 페이지로 나눌 수 있습니다.
startIndex- 컬렉션에서 시작할 위치입니다. 첫 번째 항목의 색인은 0입니다.maxResults- 반환할 최대 결과 수입니다. 기본값은 10입니다.
서가에 볼륨 추가
인증된 사용자의 서가에 볼륨을 추가하려면 다음 형식으로 URI에 HTTP POST 요청을 보냅니다.
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.
요청에 하나의 필수 쿼리 매개변수가 있습니다.
volumeId- 볼륨의 ID입니다. 볼륨 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.
요청
다음은 '즐겨찾기' 서가에 'Flowers for Algernon'을 추가하는 예입니다.
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
참고: 서가를 수정하려면 사용자 인증이 필요하므로 POST 요청과 함께 Authorization HTTP 헤더를 제공해야 합니다. 하지만 이 POST에는 데이터가 필요하지 않습니다.
응답
요청이 성공하면 서버가 204 No Content HTTP 상태 코드로 응답합니다.
선택적 쿼리 매개변수
인증된 사용자의 서가 중 하나에 볼륨을 추가할 때 표준 검색어 매개변수를 사용할 수 있습니다.
서가에서 볼륨 삭제
인증된 사용자의 서가에서 볼륨을 삭제하려면 HTTP POST를 다음 형식으로 URI에 전송합니다.
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.
요청에 하나의 필수 쿼리 매개변수가 있습니다.
volumeId- 볼륨의 ID입니다. 볼륨 ID에 관한 자세한 내용은 Google 도서 ID 섹션을 참고하세요.
요청
다음은 '즐겨찾기' 서가에서 'Flowers for Algernon'을 삭제하는 예입니다.
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
참고: 서가를 수정하려면 사용자 인증이 필요하므로 POST 요청과 함께 Authorization HTTP 헤더를 제공해야 합니다. 하지만 이 POST에는 데이터가 필요하지 않습니다.
응답
요청이 성공하면 서버가 204 No Content 상태 코드로 응답합니다.
선택적 쿼리 매개변수
인증된 사용자의 서가 중 하나에서 볼륨을 삭제할 때 표준 검색어 매개변수를 사용할 수 있습니다.
내 서가에서 모든 볼륨 삭제
인증된 사용자의 서가에서 모든 볼륨을 삭제하려면 HTTP POST를 다음 형식으로 URI에 전송합니다.
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.
요청
다음은 '즐겨찾기' 서가를 삭제하는 예입니다.
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
참고: 서가를 수정하려면 사용자 인증이 필요하므로 POST 요청과 함께 Authorization HTTP 헤더를 제공해야 합니다. 그러나 이 POST에는 데이터가 필요하지 않습니다.
응답
요청이 성공하면 서버에서 204 No Content 상태 코드를 응답으로 반환합니다.
선택적 쿼리 매개변수
인증된 사용자의 서가 중 하나에서 모든 볼륨을 삭제할 때 표준 쿼리 매개변수를 사용할 수 있습니다.
쿼리 매개변수 참조
Books API와 함께 사용할 수 있는 쿼리 매개변수가 이 섹션에 요약되어 있습니다.모든 매개변수 값은 URL로 인코딩되어야 합니다.
표준 쿼리 매개변수
모든 Books API 작업에 적용되는 쿼리 매개변수는 시스템 매개변수에 설명되어 있습니다.
API별 쿼리 매개변수
Books API의 특정 작업에만 적용되는 요청 매개변수가 다음 표에 요약되어 있습니다.
| 파라미터 | 의미 | Notes | 적용 대상 |
|---|---|---|---|
download |
다운로드 가능 여부에 따라 볼륨으로 제한합니다. |
|
|
filter |
볼륨 유형 및 사용 가능 여부를 기준으로 검색결과를 필터링합니다. |
|
|
langRestrict |
반환되는 볼륨을 지정된 언어로 태그가 지정된 볼륨으로 제한합니다. |
|
|
maxResults |
이 요청으로 반환할 요소의 최대 개수입니다. |
|
|
orderBy |
검색량이 적은 검색 결과의 순서입니다. |
|
|
printType |
도서 또는 잡지로 제한됩니다. |
|
|
projection |
반환되는 볼륨 정보를 필드 하위 집합으로 제한합니다. |
|
|
q |
전체 텍스트 쿼리 문자열입니다. |
|
|
startIndex |
컬렉션에서 결과 목록을 시작할 위치입니다. |
|
|
volumeId |
요청과 연결된 볼륨을 식별합니다. |
|