Conteúdo
Introdução
Este documento é destinado aos desenvolvedores que querem criar aplicativos que possam interagir com a API Books. O Google Livros tem a missão de digitalizar o conteúdo dos livros do mundo todo e torná-lo mais visível na Web. A API Books é uma maneira de pesquisar e acessar esse conteúdo, além de criar e visualizar personalização dele.
Se você não é familiarizado com os conceitos do Google Livros, leia Primeiros passos antes de começar a programar.
Como autorizar solicitações e identificar seu aplicativo
Toda solicitação que seu aplicativo envia para a API Books precisa identificá-lo para o Google. Há duas maneiras de identificar o aplicativo: usando o token OAuth 2.0, que também autoriza a solicitação, e/ou usando a chave de API do aplicativo. Veja como determinar a melhor opção para você:
- Se a solicitação exigir autorização (como uma solicitação de dados privados de um indivíduo), o aplicativo deverá fornecer um token OAuth 2.0 com a solicitação. O aplicativo também pode informar a chave de API, mas isso não é obrigatório.
- Se a solicitação não exige autorização, como uma solicitação de dados públicos, o aplicativo precisa fornecer a chave de API, um token OAuth 2.0 ou ambos, dependendo do que for mais conveniente para você.
Sobre protocolos de autorização
O aplicativo deve obrigatoriamente usar o OAuth 2.0 para autorizar solicitações. Não há outros protocolos de autorização compatíveis. Se o aplicativo usa o Fazer login com o Google, alguns aspectos da autorização são administrados para você.
Autorizar solicitações com OAuth 2.0
As solicitações para a API Books para dados de usuário não públicos precisam ser autorizadas por um usuário autenticado.
Os detalhes do processo de autorização ou “fluxo” para o OAuth 2.0 variam um pouco, dependendo do tipo de aplicativo que você está criando. O processo geral a seguir se aplica a todos os tipos de aplicativo:
- Ao criar seu aplicativo, registre-o usando o Console de APIs do Google. Em seguida, o Google fornece informações que serão usadas mais tarde, como um ID e uma chave secreta do cliente.
- Ative a API Books no Console de APIs do Google. Se ela não estiver no Console de APIs, pule essa etapa.
- Quando seu aplicativo precisar de acesso aos dados do usuário, ele solicitará ao Google um determinado escopo do acesso.
- O Google exibe uma tela de consentimento ao usuário, pedindo para que o aplicativo seja autorizado a solicitar alguns dos dados dele.
- Se o usuário aprovar, o Google fornecerá ao aplicativo um token de acesso de curta duração.
- O aplicativo solicita dados de usuário, anexando o token de acesso à solicitação.
- Se o Google determinar que a solicitação e o token são válidos, ele retornará os dados solicitados.
Alguns fluxos incluem etapas adicionais, como atualizar tokens para adquirir novos tokens de acesso. Para mais informações sobre fluxos de vários tipos de aplicativos, acesse a documentação OAuth 2.0 do Google.
Veja as informações de escopo do OAuth 2.0 para a API Books:
https://www.googleapis.com/auth/books
Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisa de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo, como o ID e a chave secreta do cliente.
Dica: as bibliotecas cliente de APIs do Google cuidam de parte do processo de autorização para você. Elas estão disponíveis para uma grande variedade de linguagens de programação. Verifique a página com bibliotecas e amostras para mais detalhes.
Como receber e usar uma chave de API
As solicitações de dados públicos à API Books precisam incluir um identificador, que pode ser uma chave de API ou um token de acesso.
Para adquirir uma chave de API:
- Abra a página Credenciais no Console da API.
-
Essa API aceita dois tipos de credenciais.
Crie as credenciais apropriadas para seu projeto:
-
OAuth 2.0: sempre que seu aplicativo solicitar dados particulares do usuário, ele deverá enviar um token OAuth 2.0 junto da solicitação. Primeiro, seu aplicativo envia um ID de cliente e, possivelmente, uma chave secreta do cliente para obter um token. É possível gerar credenciais OAuth 2.0 para aplicativos da Web, contas de serviço ou aplicativos instalados.
Para mais informações, acesse a documentação do OAuth 2.0.
-
Chaves de API: uma solicitação que não fornece um token OAuth 2.0 precisa enviar uma chave de API. A chave identifica seu projeto e fornece acesso à API, à cota e aos relatórios.
A API é compatível com diversos tipos de restrições em chaves de API. Se a chave de API de que você precisa ainda não existe, crie uma no console. Para isso, clique em Criar credenciais > Chave de API. É possível restringir a chave antes de usá-la na produção clicando em Restringir chave e selecionando uma das Restrições.
-
Para proteger as chaves de API, siga as práticas recomendadas para usar as chaves de API com segurança.
Depois que você tiver uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=yourAPIKey a todos os URLs de solicitação.
A chave de API é segura para ser incorporada a URLs sem precisar de codificação.
IDs do Google Livros
Você precisa especificar campos de ID com determinadas chamadas de método da API. Há três tipos de IDs usados no Google Livros:
- Códigos de volume: são strings únicas atribuídas a cada volume conhecido pelo Google Livros. Um exemplo de ID de volume é
_LettPDhwR0C. É possível usar a API para conseguir o ID do volume fazendo uma solicitação que retorne um recurso de volume. Encontre o ID do volume no campoid. - IDs da estante: valores numéricos fornecidos a uma estante na biblioteca de um usuário. O Google fornece algumas seções predefinidas para cada usuário com os seguintes IDs:
- Favoritos: 0
- Comprado: 1
- Para ler: 2
- Lendo agora: 3
- Ter lido: 4
- Revisado: 5
- Acesso recente: 6
- Meus e-books: 7
- Livros para você: 8 Se não tivermos recomendações para o usuário, esta estante não existirá.
iddele. - IDs de usuário: valores numéricos exclusivos atribuídos a cada usuário. Esses valores não são necessariamente o mesmo valor de ID usado em outros Serviços do Google. Atualmente, a única maneira de recuperar o ID do usuário é extraí-lo do selfLink em um recurso do Bookshelf recuperado com uma solicitação autenticada. Os usuários também podem obter seu próprio ID de usuário no site do Google Livros. Um usuário não pode acessar o ID de outro usuário pela API ou pelo site Livros. A outra pessoa precisaria compartilhar essas informações de maneira explícita, por e-mail, por exemplo.
IDs no site do Google Livros
Os códigos que você usa com a API Books são os mesmos usados no site do Google Livros.
- ID do volume
Ao visualizar um volume específico no site, você pode encontrar o ID do volume no parâmetro de URL
id. Confira um exemplo:https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- ID da estante
Ao visualizar uma estante específica no site, você encontra o ID dela no parâmetro de URL
as_coll. Confira um exemplo:https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
- ID do usuário
Ao visualizar sua biblioteca no site, você pode encontrar o ID do usuário no parâmetro de URL
uid. Confira um exemplo:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Definir a localização do usuário
O Google Livros respeita os direitos autorais, os contratos e outras restrições legais associadas à localização do usuário final. Como resultado, talvez alguns usuários não consigam acessar o conteúdo do livro em determinados países. Por exemplo, alguns livros podem ser visualizados somente nos Estados Unidos. Omitimos esses links de visualização para usuários em outros países. Portanto, os resultados da API são restritos com base no endereço IP do servidor ou do aplicativo cliente.
Como trabalhar com volumes
Como realizar uma pesquisa
É possível realizar uma pesquisa de volumes enviando uma solicitação GET HTTP para o seguinte URI:
https://www.googleapis.com/books/v1/volumes?q=search+terms
Esta solicitação tem um único parâmetro obrigatório:
q: pesquisa volumes que contêm essa string de texto. Você pode especificar palavras-chave especiais nos termos de pesquisa para buscar em campos específicos, como:intitle:– Retorna resultados em que o texto após a palavra-chave é encontrado no título.inauthor:– Retorna resultados em que o texto após esta palavra-chave é encontrado no autor.inpublisher:Retorna resultados em que o texto após a palavra-chave é encontrado no editor.subject:Retorna resultados em que o texto após a palavra-chave está na lista de categorias do volume.isbn:Retorna resultados em que o texto após a palavra-chave é o número ISBN.lccn:Retorna resultados em que o texto após esta palavra-chave é o Número de controle da Biblioteca do Congresso.oclc:– Retorna resultados em que o texto após essa palavra-chave é o número do Online Computer Library Center.
Solicitação
Veja um exemplo de pesquisa por "Flowers for Algernon" de Daniel Keyes:
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Observação: a realização de uma pesquisa não requer autenticação. Portanto, você não precisa fornecer o cabeçalho HTTP Authorization com a
solicitação GET. No entanto, se a chamada for feita com autenticação, cada
Volume incluirá informações específicas do usuário, como o status de compra.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um
código de status HTTP 200 OK e os resultados do volume:
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
}
Parâmetros de consulta opcionais
Além dos parâmetros de consulta padrão, é possível usar os seguintes parâmetros ao realizar uma pesquisa de volumes.
Formato de download
Use o parâmetro download para restringir os resultados retornados a volumes que tenham um formato de download disponível de epub definindo como o valor epub.
O exemplo a seguir procura livros com um download de ePub disponível:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtragem
Você pode usar o parâmetro filter para restringir ainda mais os resultados retornados, definindo-o como um dos seguintes valores:
partial: retorna resultados em que pelo menos partes do texto podem ser visualizadas.full: retorna apenas resultados em que todo o texto seja visível.free-ebooks: retorna apenas resultados que são e-books sem custo financeiro do Google.paid-ebooks: retorna apenas resultados que sejam e-books do Google com um preço.ebooks: retorna apenas resultados que são do Google e-books, pagos ou sem custo financeiro. Alguns exemplos de conteúdo que não é de e-books são revistas ou conteúdos de editores disponíveis para visualização limitada e que não estão à venda.
O exemplo a seguir restringe os resultados da pesquisa àqueles disponíveis como e-books sem custo financeiro:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Paginação
Você pode paginar a lista de volumes especificando dois valores nos parâmetros da solicitação:
startIndex: a posição na coleção em que iniciar. O índice do primeiro item é 0.maxResults: o número máximo de resultados a serem retornados. O padrão é 10, e o valor máximo permitido é 40.
Tipo de impressão
É possível usar o parâmetro printType para restringir os resultados retornados a um tipo específico de impressão ou publicação, definindo-o como um dos seguintes valores:
all: não restringe por tipo de impressão (padrão).books: retorna somente os resultados que são livros.magazines: retorna resultados que são revistas.
O exemplo a seguir restringe os resultados da pesquisa a revistas:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Projeção
É possível usar o parâmetro projection com um dos seguintes valores para especificar um conjunto predefinido de campos de volume a serem retornados:
full: retorna todos os campos de volume.lite: retorna apenas determinados campos. Consulte as descrições de campos marcadas com asteriscos duplos na Referência de volumes para descobrir quais campos estão incluídos.
O exemplo a seguir retorna resultados da pesquisa com informações de volume limitadas:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Classificação
Por padrão, uma solicitação de pesquisa de volumes retorna resultados maxResults, em que maxResults é o parâmetro usado na paginação (acima), ordenados por relevância aos termos de pesquisa.
É possível alterar a ordem definindo o parâmetro orderBy como um destes valores:
relevance: retorna os resultados na ordem de relevância dos termos de pesquisa (padrão).newest: retorna os resultados na ordem da publicação mais recente para a menos recente.
O exemplo a seguir lista os resultados por data de publicação, do mais recente ao mais antigo:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Como recuperar um volume específico
Para recuperar informações de um volume específico, envie uma solicitação HTTP GET para o URI do recurso de volume:
https://www.googleapis.com/books/v1/volumes/volumeId
Substitua o parâmetro de caminho volumeId pelo ID do volume a ser recuperado. Consulte a seção IDs do Google Livros para mais informações sobre IDs de volume.
Solicitação
Confira um exemplo de uma solicitação GET que recebe um único volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Observação: a recuperação de informações de volume não requer autenticação. Portanto, não é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET. No entanto, se a chamada for feita com
autenticação, o Volume vai incluir informações específicas do usuário, como o
status de compra.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o código de status HTTP 200 OK e o recurso de volume solicitado:
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"
}
}
Informações de acesso
A seção accessInfo é muito importante para determinar
quais recursos estão disponíveis para um e-book. Um epub é um e-book em formato de texto corrido. A seção epub terá uma propriedade isAvailable indicando se esse tipo de e-book está disponível.
Se houver uma amostra do livro ou se o usuário puder ler o livro por ter comprado ou por ser de domínio público no local do usuário, aparecerá um link de download. Um pdf para o Google Livros indica uma versão de páginas digitalizadas do e-book com detalhes semelhantes, por exemplo, se ele está disponível e um link de download. O Google recomenda arquivos epub para
e-readers e smartphones, já que páginas digitalizadas podem ser difíceis de ler nesses dispositivos.
Se não houver uma seção accessInfo, o volume não estará disponível como um e-book do Google.
Parâmetros de consulta opcionais
Além dos parâmetros de consulta padrão, é possível usar o parâmetro de consulta a seguir ao recuperar um volume específico.
Projeção
É possível usar o parâmetro projection com um dos seguintes valores para especificar um conjunto predefinido de campos de volume a serem retornados:
full: retorna todos os campos de volume.lite: retorna apenas determinados campos. Consulte as descrições de campos marcadas com asteriscos duplos na Referência de volumes para descobrir quais campos estão incluídos.
O exemplo a seguir retorna informações de volume limitadas para um único volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Trabalhar com estantes
Como recuperar uma lista de estantes públicas de um usuário
Para recuperar uma lista das estantes públicas de um usuário, envie uma solicitação GET
HTTP para o URI com o seguinte formato:
https://www.googleapis.com/books/v1/users/userId/bookshelves
Substitua o parâmetro de caminho userId pelo ID do usuário nas estantes que você quer recuperar. Consulte a seção IDs do Google Livros para mais informações sobre IDs de usuário.
Solicitação
Confira um exemplo:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
Como um usuário não precisa ser autenticado para recuperar informações sobre
estantes públicas, você não precisa fornecer o cabeçalho HTTP Authorization
com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o
código de status HTTP 200 OK e a lista de estantes:
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"
},
...
]
}
Parâmetros de consulta opcionais
É possível usar os parâmetros de consulta padrão ao recuperar a lista de estantes públicas de um usuário.
Como recuperar uma estante pública específica
Para recuperar uma estante pública específica, envie uma solicitação GET HTTP ao URI com o seguinte formato:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Substitua os parâmetros de caminho userId e px pelos IDs que especificam o usuário e o bookshelf que você quer recuperar. Consulte a seção IDs do Google Livros para mais informações.
Solicitação
Confira um exemplo:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Como um usuário não precisa ser autenticado para recuperar informações sobre
estantes públicas, você não precisa fornecer o cabeçalho HTTP Authorization
com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o código de status HTTP 200 OK e o recurso bookshelf:
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"
}
Parâmetros de consulta opcionais
É possível usar os parâmetros de consulta padrão ao recuperar uma estante pública específica.
Como recuperar uma lista de volumes em uma estante pública
Para recuperar uma lista de volumes na estante de livros pública de um usuário, envie uma solicitação GET HTTP de um URI com o seguinte formato:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Solicitação
Confira um exemplo:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Substitua os parâmetros de caminho userId e px pelos IDs que especificam o usuário e o bookshelf que você quer recuperar. Consulte a seção IDs do Google Livros para mais informações.
Como um usuário não precisa ser autenticado para recuperar informações sobre
estantes públicas, você não precisa fornecer o cabeçalho HTTP Authorization
com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status HTTP 200 OK e a lista das estantes do usuário:
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
}
Parâmetros de consulta opcionais
Além dos parâmetros de consulta padrão, é possível usar o parâmetro de consulta a seguir ao recuperar uma lista de volumes em uma estante pública.
Paginação
Você pode paginar a lista de volumes especificando dois valores nos parâmetros da solicitação:
startIndex: a posição na coleção em que iniciar. O índice do primeiro item é 0.maxResults: o número máximo de resultados a serem retornados. O padrão é 10, e o valor máximo permitido é 40.
Trabalhar com estantes em "Minha biblioteca"
Todas as solicitações de "Minha biblioteca" se aplicam aos dados do usuário autenticado.
Recuperar uma lista das minhas estantes
É possível recuperar uma lista de todas as estantes do usuário autenticado
enviando uma solicitação GET HTTP para o URI com o seguinte formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Solicitação
Confira um exemplo:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
Observação: o usuário precisa estar autenticado para recuperar uma lista de estantes
da "Minha biblioteca". Portanto, você precisa fornecer o cabeçalho HTTP Authorization com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o código de status HTTP 200 OK e a lista de todas as estantes do usuário autenticado atual:
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"
}
]
}
Parâmetros de consulta opcionais
É possível usar os parâmetros de consulta padrão ao recuperar a lista de estantes do usuário autenticado.
Como recuperar uma lista de volumes na minha estante
Recupere uma lista dos volumes na estante de livros do usuário autenticado enviando uma solicitação GET HTTP para o URI com o seguinte formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Substitua o parâmetro de caminho silver pelo ID do bookshelf. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estantes.
Solicitação
Confira um exemplo:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
Observação: o usuário precisa estar autenticado para recuperar uma listagem de
volumes da "Minha biblioteca". Portanto, você precisa fornecer o cabeçalho HTTP Authorization
com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o código de status HTTP 200 OK e a lista de volumes do bookshelf:
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
}
Parâmetros de consulta opcionais
Além dos parâmetros de consulta padrão, é possível usar o parâmetro de consulta a seguir ao recuperar uma lista de volumes em uma das estantes de livros do usuário autenticado.
Paginação
Você pode paginar a lista de volumes especificando dois valores nos parâmetros da solicitação:
startIndex: a posição na coleção em que iniciar. O índice do primeiro item é 0.maxResults: o número máximo de resultados a serem retornados. O padrão é 10.
Como adicionar um volume à minha estante
Para adicionar um volume à estante de livros do usuário autenticado, envie uma solicitação HTTP POST para o URI com o seguinte formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Substitua o parâmetro de caminho silver pelo ID do bookshelf. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estantes.
A solicitação tem um único parâmetro de consulta obrigatório:
volumeId: o ID do volume. Consulte a seção IDs do Google Livros para mais informações sobre IDs de volume.
Solicitação
Aqui está um exemplo para adicionar "Flores para Argernon" à estante de livros "Favoritos":
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
Observação: o usuário precisa estar autenticado para fazer modificações em uma estante. Portanto, forneça o cabeçalho HTTP Authorization com a solicitação POST. No entanto, nenhum dado é necessário com esse
POST.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o código de status HTTP 204 No Content.
Parâmetros de consulta opcionais
Use os parâmetros de consulta padrão ao adicionar um volume a uma das estantes do usuário autenticado.
Como remover um volume da minha estante
Para remover um volume da estante de livros do usuário autenticado, envie um POST HTTP para o URI com o seguinte formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Substitua o parâmetro de caminho silver pelo ID do bookshelf. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estantes.
A solicitação tem um único parâmetro de consulta obrigatório:
volumeId: o ID do volume. Consulte a seção IDs do Google Livros para mais informações sobre IDs de volume.
Solicitação
Veja um exemplo de remoção de "Flowers for Algernon" da estante "Favorites":
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
Observação: o usuário precisa estar autenticado para fazer modificações em uma estante. Portanto, forneça o cabeçalho HTTP Authorization com a solicitação POST. No entanto, nenhum dado é necessário com esse
POST.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status 204 No Content.
Parâmetros de consulta opcionais
Use os parâmetros de consulta padrão ao remover um volume de uma das estantes de usuários autenticados.
Como limpar todos os volumes da minha estante
Para remover todos os volumes da estante de livros do usuário autenticado, envie um
POST HTTP para o URI com o seguinte formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Substitua o parâmetro de caminho silver pelo ID do bookshelf. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estantes.
Solicitação
Veja um exemplo para limpar a estante de livros "Favoritos":
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
Observação: o usuário precisa estar autenticado para fazer modificações em uma estante. Portanto, forneça o cabeçalho HTTP Authorization com a solicitação POST. No entanto, nenhum dado é necessário com esse
POST.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status 204 No Content.
Parâmetros de consulta opcionais
É possível usar os parâmetros de consulta padrão ao limpar todos os volumes de uma das estantes do usuário autenticado.
Referência de parâmetros de consulta
Os parâmetros de consulta que você pode usar com a API Books estão resumidos nesta seção.Todos os valores de parâmetro precisam ser codificados por URL.
Parâmetros de consulta padrão
Os parâmetros de consulta que se aplicam a todas as operações da API Books estão documentados em Parâmetros do sistema.
Parâmetros de consulta específicos da API
Os parâmetros de solicitação que se aplicam apenas a operações específicas da API Books estão resumidos na tabela a seguir.
| Parâmetro | Significado | Observações | Aplicabilidade |
|---|---|---|---|
download |
Restringir a volumes por disponibilidade de download. |
|
|
filter |
Filtre os resultados da pesquisa por tipo de volume e disponibilidade. |
|
|
langRestrict |
Restringe os volumes retornados para aqueles que estão marcados com o idioma especificado. |
|
|
maxResults |
O número máximo de elementos a serem retornados com essa solicitação. |
|
|
orderBy |
Ordem dos resultados da pesquisa por volume. |
|
|
printType |
Restringir a livros ou revistas. |
|
|
projection |
Restringe informações de volume retornadas a um subconjunto de campos. |
|
|
q |
String de consulta de texto completo. |
|
|
startIndex |
A posição no conjunto em que a lista de resultados será iniciada. |
|
|
volumeId |
Identifica um volume associado à solicitação. |
|