精裝書 API 的樂趣：快速參考

我是 Goodreads 的長期用戶，但在追蹤我的書籍方面一直想嘗試更好的方法。因此，我最近開始使用 Hardcover，這是由小型獨立團隊經營的競爭對手。現在還處於早期階段，我知道很難擊敗像 Goodreads 這樣大的東西，但我充滿希望！

Hardcover 的一大優點是，與 Goodreads 不同，它有一個免費使用的 API，可讓您查詢儲存在 Hardcover 中的書籍上的任何資料。它還可以用於執行您在精裝版 UI 中能夠執行的任何操作，例如更新您正在閱讀的書籍的狀態
閱讀、將書籍加入清單等等。

我該如何使用 Hardcover 的 API

現在我正在使用 API 產生我網站的書評部分。我從 Hardcover 中獲取了所有評論，並將它們儲存在 JSON 檔案中。然後我循環瀏覽此列表中的評論，並將它們全部呈現在頁面上。

我不太確定如何處理非常短的評論，因此目前我決定在頁面上按原樣呈現評論（如果評論少於360 個字元），並連結到單獨的頁面（如果評論少於360 個字元）他們的意義遠不止於此。

我還添加了一個搜尋欄，它將搜尋我的所有評論，並且如果評論中有劇透，我還設定了一些文字模糊處理。

將來我想加入一種按星級和流派進行過濾的方法。

開始使用 Hardcover 的 API

Hardcover 的 API 也處於早期存取模式，並且還沒有任何適當的文檔，因此在這篇文章中我將回顧一些迄今為止我發現有用的查詢。 Hardcover 的 Discord 伺服器也是取得問題答案的好地方。

您首先需要前往設定頁面，並取得精裝版 API 金鑰。然後您可以在 Hardcover 的 GraphQL 控制台中測試您的查詢。

獲取您讀過的所有書籍

從基本的 GraphQL 查詢開始，我們可以使用 status_id 進行過濾，以獲取您在精裝本中標記為“已讀”的所有書籍的書名列表：

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

我們已將其封裝在我中，您可以使用它來查詢特定於您的用戶的任何內容。

status_id 值的工作方式是：

• 1：一本「想讀」的書
• 2：一本「正在閱讀」的書
• 3：一本「讀過」的書
• 5：「一本沒有完成」的書

取得一本書的作者

如果您搜尋cached_contributors，您將獲得一個包含書籍「貢獻者」清單的陣列。這將包含一組預定的數據，例如貢獻者的姓名、ID 和圖像。

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

他們是「貢獻者」而不是「作者」的原因是它還可以包含翻譯該書的人的名字。如果有多個作者，他們也會全部出現在清單中。如果您查詢的是一本由一位作者撰寫的普通小說，則使用清單中的第一項通常就可以了。

快取版本的查詢速度更快，但如果您想要特定的內容，您也可以查詢非快取版本：

book {
  cached_contributors
}

取得書籍的精裝書 URL

如果您想獲取該書的精裝版鏈接，可以查詢其slug：

book {
  title
    contributions {
      author {
        name
       }
    }
 }

slug 是網站網域後面的字串，例如在 emgoto.com/hardcover-book-api 上，「hardcover-book-api」位元就是 slug。

因此，一旦您獲得了 slug，您只需在其開頭添加 https://hardcover.app/books/ 即可建立您的精裝版 URL。

取得書籍上的流派標籤

精裝本中的流派標籤系統是用戶生成的。您可以查詢cached_tags，它將按從最多標記到最少標記的順序傳回標記。

book {
  slug
}

取得完整的標籤清單後，您可以使用cached_tags['Genre'] 來取得特定於流派的標籤。

如果很多人將某本書標記為小說，那麼這將是清單中顯示的第一個類型。有趣的是，人們喜歡給他們的書貼上奇幻的標籤，因此這種類型經常出現在小說標籤之前。人們非常喜歡為自己的書貼上奇幻標籤，以至於像《沙丘》這樣的科幻書籍甚至最終也貼上了科幻和奇幻的標籤。

如果您要使用此數據，我建議先對其進行一些清理。例如，如果這本書同時具有奇幻和科幻作為類型標籤，則僅使用清單中第一個標籤並丟棄另一個標籤，因為這更有可能是準確的。

將一本書加入您的「待讀」列表

到目前為止，我只涉及了獲取數據，但你也可以使用Hardcover 的API 來操作數據- 當然你不能接觸任何其他人的東西，但你可以在自己的Hardcover 帳戶上做的任何事情都是公平的遊戲.

如果您有書籍的 ID，您可以透過將其 status_id 設定為 1 將其新增至「待讀」清單：

book {
  cached_tags
}

獲取您的書評

這是我用來獲取我在精裝本中寫的所有評論的方法：

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

我幾乎所有的書籍和評論都是從 Goodreads 導入的，我認為有時資料在導入過程中會有點混亂。我發現按 date_added 和 reviewed_at 排序更準確。

我使用 review_raw 值來獲取評論文本，其中不包含任何格式（如換行符）。不幸的是，這意味著如果您的評論中有多個段落，API 會將其全部吐出為一個長段落，如下所示：

book {
  cached_contributors
}

使用 JavaScript，我透過執行如下所示的正規表示式來解決這個問題：

book {
  title
    contributions {
      author {
        name
       }
    }
 }

如果有任何句點後面沒有空格，您可以猜測這應該是一個新段落並添加雙換行符 nn。這會建立一個新段落。

另一個缺點是劇透標籤也丟失了，所以你必須手動添加它們。

還有一個 review_html 值，我認為它可能更有用，但不幸的是它對我來說似乎總是為空。同樣，如果您有一篇包含劇透的評論，則會有一個 review_has_spoilers 值，但對於我從 Goodreads 導入的所有書籍，該值都是 false，因此您可能無法依賴它。

按書名和/或作者搜尋書籍

精裝書的圖書搜尋非常準確，但他們的 API 中沒有 1-1 版本。您可以透過多種方式嘗試模仿他們的搜尋行為，但快速入門的方法是使用 _eq:
在標題上進行搜索

book {
  slug
}

我按照 users_read_count 排序了圖書列表，因為讀者數量最多的名為《Dune》的書很可能就是您要找的《Dune》。

如果您想按標題和作者進行過濾，過濾器查詢將如下所示：

book {
  cached_tags
}

如果您不想進行精確的字串匹配，可以使用 _ilike 查詢來代替，它不匹配大小寫，因此使用小寫字母仍然有效：

mutation addBook {
  insert_user_book(object: {book_id: 123, status_id: 1}) {
    id
  }
}

您也可以使用 % 字元作為 _ilike 的通配符，這樣就可以

{
  me {
    user_books(
      where: { _and: [ 
        {has_review: {_eq: true}},
        {status_id: {_eq: 3 }}
      ]}
      order_by: [
        { date_added: desc },
        { reviewed_at: desc }
      ]
    ) {
      reviewed_at
      date_added
      review_raw
      rating
      book {
        title
      }
    }
  }
}

它將匹配任何包含單字“frank”的作者。

順便說一句，由於 Hardcover 使用 Hasura，Google搜尋「如何在 Hasura 中執行 X」通常會顯示如何執行這些更複雜的查詢。

將書籍添加到您的精裝書清單中

除了標準的「想讀」和「已讀」清單外，精裝版還具有單獨的自訂清單功能。要取得所有清單以及其中的書籍，您可以執行以下操作：

this is the end of one paragraph.And this is the start of the next

將一本書加入清單中

如果您想將一本書新增到清單中，首先您需要取得清單 ID 和圖書 ID。那就很簡單了：

{
  me {
    user_books(where: {status_id: {_eq: 3}}) {
      rating
      book {
        title
      }
    }
  }
}

使用 JavaScript 進行 API 呼叫

一旦您想要退出 GraphQL 控制台，您可以使用 fetch() 進行 API 呼叫。作為一個非常簡單的例子，這是我獲取所有評論（我已經將其縮寫了一點）：

book {
  cached_contributors
}

我必須讓建立 fetch 呼叫變得更容易的程式設計專業技巧是，如果您：

• 前往精裝本
• 在「網路」標籤中搜尋 graphql
• 找到一個看起來有用且正在回傳資訊的
• 右鍵點選網路呼叫>;複製>複製為擷取

它將為您複製一個與我上面貼上的類似的 fetch 調用，然後您可以在自己的程式碼中使用它。

關於速率限制的說明

一旦您移出 GraphQL 控制台並開始在腳本中執行操作，如果您嘗試同時執行太多操作，則可能會遇到錯誤或速率限制問題。

例如，當在清單中新增一本新書時，我發現嘗試同時新增兩本書會在 API 中出錯，可能是因為它試圖將兩本書新增到清單中的同一位置。

類似地，如果您嘗試發出 100 個不同的呼叫來根據書名搜尋一本書，其中一些呼叫將會逾時。如果您將它們展開並每秒執行一次，如下所示，那麼您應該不會遇到任何問題：

book {
  title
    contributions {
      author {
        name
       }
    }
 }

此外，如果您從 Hardcover 中獲取一本書的圖像 URL，然後嘗試在您的頁面上同時加載 100 本書的圖像，API 會限制您的速率，並且某些圖像將無法加載。我建議在圖片標籤中加入“loading=lazy”，如下所示：

book {
  slug
}

這樣，只有當使用者向下捲動查看圖片時才會載入圖片。

就是這樣！我很想知道精裝本的下一步發展——我希望它能做得很好，我們終於有了一個 Goodreads 殺手。如果你想在精裝本上關注我，我很幸運地找到了 @emma 帳號。

以上是精裝書 API 的樂趣：快速參考的詳細內容。更多資訊請關注PHP中文網其他相關文章！