ハードカバーの書籍 API を楽しむ: クイック リファレンス

私は長年 Goodreads を使用していますが、書籍の追跡に関しては、もっと良いものを試してみたいと常々思っていました。そこで私は最近、小規模なインディーズチームが運営する競合他社である Hardcover を使い始めました。まだ初期段階にあり、Goodreads のような規模のものに勝つのは難しいことはわかっていますが、期待しています!

ハードカバーの優れた点の 1 つは、Goodreads とは異なり、無料で使用できる API があり、ハードカバーに保存されている書籍のデータをクエリできることです。また、書籍のステータスを更新するなど、ハードカバー UI で自分で実行できることは基本的にすべて実行するために使用できます
読書、リストへの本の追加など。

Hardcover の API の使用方法

現在、API を使用してサイトの書評セクションを生成しています。すべてのレビューをハードカバーから取得し、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: 「A は終了しませんでした」本

本の著者を取得する

cached_contributors を検索すると、書籍への「寄稿者」のリストを含む配列が得られます。これには、投稿者の名前、ID、画像などの所定のデータ セットが含まれます。

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

彼らが「著者」ではなく「寄稿者」である理由は、その本を翻訳した人の名前も含まれる場合があるためです。複数の著者がいる場合は、それらもすべてリストに含まれます。 1 人の著者による通常のフィクション本をクエリする場合は、通常、リストの最初の項目を使用すれば問題ありません。

キャッシュされたバージョンの方がクエリが高速ですが、何か特定のことが必要な場合は、キャッシュされていないコントリビューションに対してクエリを実行することもできます。

book {
  cached_contributors
}

書籍のハードカバー URL を取得する

ハードカバーの書籍のリンクを取得したい場合は、そのスラッグをクエリできます。

book {
  title
    contributions {
      author {
        name
       }
    }
 }

スラッグは、Web サイトのドメイン名の後の文字列です。 emgoto.com/hardcover-book-api では、「hardcover-book-api」ビットがナメクジです。

スラッグを取得したら、その先頭に https://hardcover.app/books/ を追加してハードカバー URL を作成するだけです。

本のジャンルタグを取得する

ハードカバーのジャンルタグシステムはユーザーが作成したものです。キャッシュされたタグに対してクエリを実行すると、タグが最も多いものから最も少ないものへの順序でタグが返されます。

book {
  slug
}

タグの完全なリストを取得したら、cached_tags['Genre'] を使用してジャンル固有のリストを取得できます。

多くの人が特定の本をフィクションとしてタグ付けしている場合、それがリストに最初に表示されるジャンルになります。興味深いことに、人々は自分の本にファンタジーというタグを付けるのが好きなため、このジャンルはフィクションのタグの前に表示されることがよくあります。人々は自分の本にファンタジーのタグを付けるのが大好きなので、『デューン』のような SF 本には SF とファンタジーの両方のタグが付けられることもあります。

このデータを使用する場合は、最初に少しクリーンアップすることをお勧めします。たとえば、本のジャンル タグとしてファンタジーと SF の両方が含まれている場合、リストの最初にある方のみを使用し、もう一方は破棄します。そのほうが正確である可能性が高いためです。

「読みたい」リストに本を追加する

これまでのところ、データの取得についてのみ触れてきましたが、Hardcover の API を使用してデータを操作することもできます。もちろん、他人のものに触ることはできませんが、自分の Hardcover アカウントで実行できることはすべて問題ありません。 .

書籍の ID をお持ちの場合は、status_id を 1: に設定することで、その書籍を「読みたい」リストに追加できます。

book {
  cached_tags
}

本のレビューを受け取る

これは、私がハードカバーで書いたすべてのレビューを取得するために使用するものです:

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

私の書籍とレビューのほぼすべてが Goodreads からインポートされているのですが、インポート中にデータが少し混乱することがあると思います。 dated_added と reviews_at の両方で並べ替えた方がより正確であることがわかりました。

レビュー テキストを取得するために review_raw 値を使用しました。これには改行などの書式設定が含まれていません。これは残念ながら、レビューに複数の段落がある場合、API は次のようにすべてを 1 つの長い段落として吐き出すことを意味します:

book {
  cached_contributors
}

JavaScript では、次のような正規表現を実行することでこの問題を回避しました。

book {
  title
    contributions {
      author {
        name
       }
    }
 }

その後にスペースのないピリオドがある場合は、これが新しい段落であると推測し、二重改行 nn を追加できます。新しい段落が作成されます。

もう 1 つの欠点は、ネタバレタグも欠落しているため、これらを手動で追加する必要があることです。

review_html 値もあります。これはもっと便利かもしれないと思いましたが、残念ながら、私にとっては常に null のようです。同様に、ネタバレを含むレビューがある場合、review_has_spoilers 値がありますが、Goodreads からインポートしたすべての書籍では、この値は false であるため、信頼できない可能性があります。

タイトルや著者で本を検索する

ハードカバーの書籍検索はかなり正確ですが、API にはこれの 1-1 バージョンがありません。彼らの検索動作を真似してみる方法はたくさんありますが、手っ取り早い方法は、_eq:
を使用してタイトルで検索することです。

book {
  slug
}

読者数が最も多い Dune という本があなたが探している Dune である可能性が高いため、users_read_count で本のリストを並べました。

タイトルと著者でフィルタリングしたい場合、フィルタクエリは次のようになります:

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」という単語を含む任意の著者に一致します。

余談ですが、ハードカバーでは Hasura が使用されているため、「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
}

フェッチ呼び出しの構築を簡単にするためのプログラミングのプロのヒントは、次のような場合に役立ちます。

• ハードカバーに移動
• 「ネットワーク」タブでgraphqlを検索します
• 便利そうな、情報を返してくれるものを見つけてください
• ネットワーク通話を右クリック >コピー >フェッチとしてコピー

上に貼り付けたものと同様のフェッチ呼び出しがコピーされ、独自のコードで使用できます。

レート制限に関する注意事項

GraphQL コンソールから移動してスクリプトで作業を開始すると、同時に多くのことを実行しようとすると、エラーやレート制限の問題が発生する可能性があります。

たとえば、新しい本をリストに追加するときに、2 冊を同時に追加しようとすると API でエラーが発生することがわかりました。おそらく、リスト内の同じ位置に 2 冊の本を追加しようとしているためです。

同様に、タイトルに基づいて書籍を検索するために 100 回の異なる呼び出しを行おうとした場合、これらの呼び出しの一部はタイムアウトになります。以下のようにそれらを分散して 1 秒ごとに実行すれば、問題は発生しないはずです。

book {
  title
    contributions {
      author {
        name
       }
    }
 }

また、ハードカバーから書籍の画像 URL を取得し、同時に 100 冊の書籍の画像をページにロードしようとすると、API によってレート制限がかかり、一部の画像はロードされません。次のように画像タグにloading=lazyを入れることをお勧めします:

book {
  slug
}

この方法では、ユーザーが下にスクロールして画像を表示したときにのみ画像が読み込まれます。

それで終わりです!私はハードカバーが次にどこに行くのかに注目しています。ハードカバーがうまくいくことを願っています。そしてついに、Goodreads キラーを手に入れることができました。ハードカバーで私をフォローしたい場合は、偶然にも @emma ハンドルを手に入れることができました。

以上がハードカバーの書籍 API を楽しむ: クイック リファレンスの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。