API 사용

목차

  1. 소개
    1. 인증 및 승인
    2. Google 도서 ID
    3. 사용자 위치 설정
  2. 볼륨 작업
    1. 검색 실행
    2. 특정 볼륨 검색
  3. 서가 작업
    1. 사용자의 공개 보관함 목록 검색
    2. 특정 공개 보관함 검색
    3. 공개 보관함의 볼륨 목록 가져오기
  4. '내 라이브러리'에서 보관함 사용하기
    1. 내 보관함 목록 가져오기
    2. 내 보관함의 볼륨 목록 가져오기
    3. 서가에 볼륨 추가하기
    4. 책장 도서 삭제하기
    5. 내 보관함에서 모든 볼륨 삭제하기
  5. 쿼리 매개변수 참조
    1. 표준 쿼리 매개변수
    2. API별 쿼리 매개변수

소개

이 문서는 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의 세부적인 승인 절차('흐름')는 제작 중인 애플리케이션 종류에 따라 약간씩 다릅니다. 다음의 일반적인 과정은 모든 애플리케이션 유형에 적용됩니다.

  1. 애플리케이션을 만들 때 Google API 콘솔을 사용하여 애플리케이션을 등록합니다. 이렇게 하면 Google에서 클라이언트 ID 및 클라이언트 보안 비밀과 같이 나중에 필요한 정보를 제공합니다.
  2. Google API 콘솔에서 Books API를 활성화합니다. API 콘솔의 목록에 이 API가 없다면 이 단계를 건너뜁니다.
  3. 애플리케이션에서 사용자 데이터에 액세스해야 하는 경우 Google에 특정 액세스 범위를 요청합니다.
  4. Google에서 사용자에게 애플리케이션이 일부 데이터를 요청하도록 승인할 것인지 물어보는 동의 화면을 표시합니다.
  5. 사용자가 승인하면 Google에서 애플리케이션에 제한 시간이 있는 액세스 토큰을 제공합니다.
  6. 애플리케이션에서 액세스 토큰을 첨부하여 사용자 데이터를 요청합니다.
  7. 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 키를 획득하려면 다음 안내를 따르세요.

  1. API 콘솔에서 사용자 인증 정보 페이지를 엽니다.
  2. 이 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는 1,000보다 큽니다. 보관함 ID는 특정 사용자에게 고유합니다. 즉, 두 사용자가 동일한 ID를 가진 보관함을 보유할 수 있지만 서로 다른 보관함을 참조할 수 있습니다. API를 사용하여 Bookshelf 리소스를 반환하는 요청을 실행하여 Bookshelf ID를 가져올 수 있습니다. Bookshelf ID는 id 필드에서 찾을 수 있습니다.
  • 사용자 ID: 각 사용자에게 할당된 고유한 숫자 값입니다. 이러한 값은 다른 Google 서비스에서 사용되는 ID 값과 반드시 동일하지는 않습니다. 현재 사용자 ID를 가져오는 유일한 방법은 인증된 요청으로 가져온 북마크 리소스의 selfLink에서 추출하는 것입니다. 사용자는 북 사이트에서 자신의 사용자 ID를 가져올 수도 있습니다. 사용자는 API 또는 Books 사이트를 통해 다른 사용자의 사용자 ID를 가져올 수 없습니다. 다른 사용자가 이메일 등을 통해 해당 정보를 명시적으로 공유해야 합니다.

Google 도서 사이트의 ID

Books API에 사용하는 ID는 Google 북스 사이트에서 사용하는 ID와 동일합니다.

  • 볼륨 ID

    사이트에서 특정 볼륨을 볼 때 id URL 매개변수에서 볼륨 ID를 찾을 수 있습니다. 예를 들면 다음과 같습니다. 

    https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

  • Bookshelf ID

    사이트에서 특정 보관함을 볼 때 as_coll URL 매개변수에서 보관함 ID를 찾을 수 있습니다. 예를 들면 다음과 같습니다. 

    https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

  • 사용자 ID

    사이트에서 라이브러리를 볼 때 uid URL 매개변수에서 사용자 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: 이 키워드 뒤의 텍스트가 Library of Congress Control Number인 결과를 반환합니다.
    • oclc: 이 키워드 뒤의 텍스트가 온라인 컴퓨터 도서관 센터 번호인 검색 결과를 반환합니다.

요청

다음은 다니엘 키즈의 '알제르논을 위한 꽃다발'을 검색하는 예입니다. 

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인 볼륨으로 반환 결과를 제한합니다.

다음 예에서는 epub 다운로드가 가능한 도서를 검색합니다.

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을 나타냅니다. 스캔한 페이지를 이러한 기기에서 읽기 어려울 수 있으므로 전자책 리더와 스마트폰에는 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 */

참고: '내 보관함' 볼륨 목록을 가져오려면 사용자가 인증되어야 합니다. 따라서 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 상태 코드로 응답합니다.

선택적 쿼리 매개변수

인증된 사용자의 보관함 중 하나에 볼륨을 추가할 때 표준 쿼리 매개변수를 사용할 수 있습니다.

보관함에서 볼륨 삭제하기

인증된 사용자의 보관함에서 볼륨을 삭제하려면 다음 형식으로 URI에 HTTP POST를 전송합니다.

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 상태 코드로 응답합니다.

선택적 쿼리 매개변수

인증된 사용자의 보관함 중 하나에서 볼륨을 삭제할 때 표준 쿼리 매개변수를 사용할 수 있습니다.

보관함에서 모든 볼륨 삭제

인증된 사용자의 보관함에서 모든 볼륨을 삭제하려면 다음 형식으로 URI에 HTTP POST를 전송합니다.

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의 특정 작업에만 적용되는 요청 매개변수가 다음 표에 요약되어 있습니다.

매개변수 의미 참고 적용 대상
download 다운로드 가능 여부에 따라 볼륨으로 제한합니다.
  • 현재 유일하게 지원되는 값은 epub입니다.
  • 다운로드 액세스 권한을 얻으려면 구매해야 할 수도 있습니다.
filter 볼륨 유형 및 재고 여부에 따라 검색 결과를 필터링합니다.
  • 지원되는 필터는 다음과 같습니다.
    • filter=partial - 텍스트의 일부라도 미리 볼 수 있는 볼륨으로 결과를 제한합니다.
    • filter=full - 모든 텍스트를 볼 수 있는 볼륨으로 결과를 제한합니다.
    • filter=free-ebooks - 결과를 무료 Google eBook으로 제한합니다.
    • filter=paid-ebooks - 구매 가격이 있는 Google eBook으로 결과를 제한합니다.
    • filter=ebooks - 유료 또는 무료 Google eBook으로 검색 결과를 제한합니다.eBook이 아닌 콘텐츠의 예로는 판매용이 아닌 제한된 미리보기로 제공되는 게시자 콘텐츠 또는 잡지가 있습니다.

 
langRestrict 지정된 언어로 태그된 볼륨으로 반환되는 볼륨을 제한합니다.
  • langRestrict를 두 글자 ISO-639-1 코드(예: 'en' 또는 'fr')로 지정하여 검색 결과를 특정 언어로 제한합니다.
maxResults 이 요청과 함께 반환할 최대 요소 수입니다.
  • 컬렉션의 모든 항목에 대한 요청의 경우 요청 매개변수에 startIndex 및 maxResults를 지정하여 결과를 페이지로 나눌 수 있습니다.
  • 기본값: maxResults=10
  • 최대 허용 값: maxResults=40.
orderBy

검색량 검색 결과의 순서입니다.

  • 기본적으로 검색 요청은 maxResults 결과를 반환합니다. 여기서 maxResults는 페이지 매김에 사용되는 매개변수이며 가장 관련성이 높은 순으로 정렬됩니다.
  • orderBy 매개변수를 다음 값 중 하나로 설정하여 순서를 변경할 수 있습니다.
    • orderBy=relevance - 가장 관련성이 높은 검색 결과부터 가장 관련성이 낮은 검색 결과 순으로 반환합니다 (기본값).
    • orderBy=newest - 최신 게시일 순으로 검색 결과를 반환합니다.
printType 책 또는 잡지로 제한합니다.
  • 지원되는 값은 다음과 같습니다.
    • printType=all - 모든 볼륨 콘텐츠 유형을 반환합니다 (제한 없음). 이는 기본값입니다.
    • printType=books - 도서만 반환합니다.
    • printType=magazines - 잡지만 반환합니다.
projection 반환되는 볼륨 정보를 필드 하위 집합으로 제한합니다.
  • 지원되는 투영은 다음과 같습니다.
    • projection=full - 모든 볼륨 메타데이터를 포함합니다 (기본값).
    • projection=lite - 볼륨 및 액세스 메타데이터의 제목만 포함합니다.
q 전체 텍스트 쿼리 문자열
  • 쿼리를 만들 때는 검색어를 '+'로 구분하여 q=term1+term2_term3 형식으로 나열합니다. 또는 공백으로 구분할 수도 있지만, 이 경우 모든 쿼리 매개변수 값과 마찬가지로 공백을 URL로 인코딩해야 합니다. API는 모든 검색어와 일치하는 모든 항목을 반환합니다 (검색어 사이에 AND를 사용하는 경우). Google의 웹 검색과 마찬가지로 API는 하위 문자열이 아닌 전체 단어 (및 동일한 접두사가 있는 관련 단어)를 검색합니다.
  • 정확한 구문을 검색하려면 구문을 따옴표로 묶습니다(q="exact phrase").
  • 지정된 용어와 일치하는 항목을 제외하려면 q=-term 양식을 사용합니다.
  • 검색어는 대소문자를 구분하지 않습니다.
  • 예: "Elizabeth Bennet"라는 정확한 문구와 "Darcy"라는 단어는 포함하지만 "Austen"라는 단어는 포함하지 않는 모든 항목을 검색하려면 다음 쿼리 매개변수 값을 사용하세요.
    q="Elizabeth+Bennet"+Darcy-Austen
  • 검색어에 특정 필드에서 검색할 수 있는 다음과 같은 특수 (대소문자 구분) 키워드를 지정할 수 있습니다.
    • intitle: 이 키워드 다음에 오는 텍스트가 제목에 포함된 결과를 반환합니다.
    • inauthor: 이 키워드 다음에 오는 텍스트가 저자에서 발견된 결과를 반환합니다.
    • inpublisher: 이 키워드 다음에 오는 텍스트가 게시자에서 발견된 결과를 반환합니다.
    • subject: 이 키워드 다음에 오는 텍스트가 볼륨의 카테고리 목록에 있는 결과를 반환합니다.
    • isbn: 이 키워드 뒤에 오는 텍스트가 ISBN 번호인 결과를 반환합니다.
    • lccn: 이 키워드 뒤의 텍스트가 Library of Congress Control Number인 결과를 반환합니다.
    • oclc: 이 키워드 뒤의 텍스트가 온라인 컴퓨터 도서관 센터 번호인 결과를 반환합니다.
startIndex 결과 목록을 시작할 컬렉션의 위치입니다.
  • 컬렉션의 모든 항목에 대한 요청의 경우 요청 매개변수에 startIndex 및 maxResults를 지정하여 결과 페이지를 설정할 수 있습니다.
  • 첫 번째 항목의 색인은 0입니다.
volumeId 요청과 연결된 볼륨을 식별합니다.
  • 보관함에 추가하거나 보관함에서 삭제할 볼륨을 지정합니다.