cheerio-httpcli - Node.js用WEBスクレイピングモジュール

Node.jsでWEBページのスクレイピングを行う際に必要となる文字コードの変換と、cheerioによってパースしたHTMLをjQueryのように操作できるHTTPクライアントモジュールです。

特徴

1. 取得先WEBページの文字コードを自動で判定してHTMLをUTF-8に変換
2. UTF-8に変換したHTMLをjQueryのように操作可能
3. フォームの送信やリンクのクリックをエミュレート
4. フォーム送信時のファイルアップロード対応
5. Node.jsお馴染みのコールバック形式と最近の流行であるプロミス形式どちらにも対応
6. 同期リクエスト対応
7. $('a')要素のリンク先をファイルとしてダウンロード可能
8. $('img')要素画像をファイルとしてダウンロード可能(LazyLoad対応)
9. $('a,img,script,link')要素のURLを絶対パスで取得可能
10. ブラウザ指定による簡単User-Agent切り替え機能
11. マルチインスタンス(ログインが必要な同一サイトに複数のアカウントで同時ログイン)対応
12. Puppeteerと互換性のあるクッキーJSONファイルの保存・読み込み対応

> 静的なHTMLをベースに処理するモジュールなのでSPAなどクライアントサイドのJavaScriptによってコンテンツを取得/変更するタイプのWEBページには対応していません。

サンプル

var client = require('cheerio-httpcli');

// Googleで「node.js」について検索する。
var word = 'node.js';

client.fetch('https://www.google.com/search', { q: word }, function (err, $, res, body) {
  // レスポンスヘッダを参照
  console.log(res.headers);

  // HTMLタイトルを表示
  console.log($('title').text());

  // リンク一覧を表示
  $('a').each(function (idx) {
    console.log($(this).attr('href'));
  });
});

同梱のexample/google.jsはGoogle検索結果の一覧を取得するサンプルです。参考にしてください。

インストール

npm install cheerio-httpcli

API目次

• メソッド
  • fetch()
  • fetchSync()
  • set()
  • setBrowser()
  • setIconvEngine()
  • reset()
  • fork()
  • exportCookies()
  • importCookies()
• プロパティ
  • version
  • browser
  • iconv
  • headers
  • timeout
  • gzip
  • referer
  • followMetaRefresh
  • maxDataSize
  • forceHtml
  • agentOptions
  • debug
  • download
• cheerioオブジェクトの独自拡張
  • $.documentInfo()
  • $(link-element or submit-element).click()
  • $(link-element or submit-element).clickSync()
  • $(form-element).submit()
  • $(form-element).submitSync()
  • $(form-element).field()
  • $(checkbox-element or radio-element).tick()
  • $(checkbox-element or radio-element).untick()
  • $(link-element or image-element).url()
  • $(link-element or image-element).download()
  • $(element).entityHtml()

メソッド

fetch(url[, get-param, encode, callback])

urlで指定したWEBページをGETメソッドで取得し、文字コードの変換とHTMLパースを行いcallback関数に返します。

callback関数には以下の4つの引数が渡されます。

1. Errorオブジェクト
2. cheerio.load()でHTMLコンテンツをパースしたオブジェクト(独自拡張版)
3. requestモジュールのresponseオブジェクト(独自拡張版)
4. UTF-8に変換したHTMLコンテンツ

各種引数の指定

• GET時にパラメータ(?foo=bar&hoge=fuga)を付加する場合は第2引数のget-paramに連想配列で指定します。

• あらかじめ取得対象のWEBページのエンコーディングが分かっている場合はencodeにsjisやeuc-jpなどの文字列をセットすることで自動判定による誤判定(滅多に発生しませんが)を防止することができます。

• get-param、encode、場合によってはcallbackも省略可能です。

  // get-paramとencodeを省略 => GETパラメータ指定なし & エンコーディング自動判定
  client.fetch('https://hogehoge.com/fuga.html', function (err, $, res, body) {
    ...
  });
  
  // get-paramを省略 => GETパラメータ指定なし & エンコーディング指定(sjis)
  client.fetch('https://hogehoge.com/fuga.html', 'sjis', function (err, $, res, body) {
    ...
  });
  
  // encodeを省略 => GETパラメータ指定(?foo=bar) & エンコーディング自動判定
  client.fetch('https://hogehoge.com/fuga.html', { foo: 'bar' }, function (err, $, res, body) {
    ...
  });
  
  // url以外全部省略 => GETパラメータ指定なし & エンコーディング自動判定 & プロミス形式(後述)
  client.fetch('https://hogehoge.com/fuga.html')
  .then(function (result) {
    ...
  });
  

プロミス形式での呼び出し

fetch()の第4引数であるcallback関数を省略すると、戻り値としてPromiseオブジェクトが返ります。先ほどのサンプルをプロミス形式で呼び出すと以下のようになります。

var client = require('cheerio-httpcli');

// Googleで「node.js」について検索する。
var word = 'node.js';

// callbackを指定しなかったのでPromiseオブジェクトが返る
var p = client.fetch('https://www.google.com/search', { q: word })
p.then(function (result) {
  // レスポンスヘッダを参照
  console.log(result.response.headers);

  // HTMLタイトルを表示
  console.log(result.$('title').text());

  // リンク一覧を表示
  result.$('a').each(function (idx) {
    console.log(result.$(this).attr('href'));
  });
})

p.catch(function (err) {
  console.log(err);
});

p.finally(function () {
  console.log('done');
});

callback関数を指定しないfetch()の戻り値をp変数が受け取り、そのp変数を通してthen(正常終了時)およびcatch(エラー発生時)の処理を行っています。また、正常終了でもエラーでも必ず最後に通る処理であるfinallyも使用できます。

thenに渡されるパラメータはコールバック形式で呼び出した際にcallback関数に渡されるものと同じですが、第1引数のオブジェクトにまとめて入っているという点で異なるのでご注意ください。

• error ... Errorオブジェクト
• $ ... cheerio.load()でHTMLコンテンツをパースしたオブジェクト(独自拡張版)
• response ... requestモジュールのresponseオブジェクト(独自拡張版)
• body ... UTF-8に変換したHTMLコンテンツ

.then(function (result) {
  console.log(result);
  // => {
  //      error: ...,
  //      $: ...,
  //      response: ...,
  //      body: ...
  //    };
});

プロミス形式を活かした使い方

とあるサイトのトップページにアクセスして、その中のとあるページに移動して...というように順を追ってWEBページに潜っていきたい場合などもメソッドチェーンでこんな感じに書くことができます。

var client = require('cheerio-httpcli');

client.fetch(