session
session
モジュールは、新しいSession
オブジェクトを作成するのに使われます。
BrowserWindow
のプロパティである webContents
プロパティのsession
を使うことで既存ページの session
にアクセスできます。
const BrowserWindow = require('electron').BrowserWindow
var win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com')
var ses = win.webContents.session
メソッド
session
メソッドは次のメソッドを持ちます:
session.fromPartition(partition)
partition
String
partition
文字列から新しいSession
インスタンスを返します。
partition
がpersist:
から始まっている場合、同じpartition
のアプリ内のすべてのページに永続セッションを提供するのにページが使います。persist:
プレフィックスが無い場合、ページはインメモリセッションを使います。partition
が空の場合、アプリの既定のセッションを返します。
プロパティ
session
モジュールは次のプロパティを持ちます:
session.defaultSession
アプリの既定のセッションオブジェクトを返します。
クラス: Session
session
モジュールで、Session
オブジェクトを作成できます:
const session = require('electron').session
var ses = session.fromPartition('persist:name')
インスタンスイベント
Session
のインスタンス上で次のイベントが提供されます:
イベント: 'will-download'
event
Eventitem
DownloadItemwebContents
WebContents
ElectronがwebContents
でitem
をダウンロードしようとすると出力されます。
event.preventDefault()
をコールするとダウンロードをキャンセルできます。
session.defaultSession.on('will-download', function (event, item, webContents) {
event.preventDefault()
require('request')(item.getURL(), function (data) {
require('fs').writeFileSync('/somewhere', data)
})
})
インスタンスのメソッド
Session
のインスタンス上で次のメソッドが提供されています:
ses.cookies
cookies
は、cookiesに問い合わせしたり、修正をできるようにします。例:
// Query all cookies.
session.defaultSession.cookies.get({}, function (error, cookies) {
if (error) console.error(error)
console.log(cookies)
})
// Query all cookies associated with a specific url.
session.defaultSession.cookies.get({ url: 'http://www.github.com' }, function (error, cookies) {
if (error) console.error(error)
console.log(cookies)
})
// Set a cookie with the given cookie data;
// may overwrite equivalent cookies if they exist.
var cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }
session.defaultSession.cookies.set(cookie, function (error) {
if (error) console.error(error)
})
ses.cookies.get(filter, callback)
filter
Objecturl
String (オプション) -url
に関連付けられているcookiesを取得します。空の場合すべてのurlのcookiesを取得しますname
String (オプション) -name
でcookiesをフィルタリングしますdomain
String (オプション) -domains
のドメインまたはサブドメインに一致するcookiesを取得しますpath
String (オプション) -path
に一致するパスのcookiesを取得しますsecure
Boolean (オプション) - Secure プロパティでcookiesをフィルターしますsession
Boolean (オプション) - Filters outsession
または永続cookiesを除外します
callback
Function
details
に一致するすべてのcookiesを取得するためにリクエストを送信し、完了時にcallback(error, cookies)
でcallback
がコールされます。
cookies
はcookie
オブジェクトの配列です。
cookie
Objectname
String - cookieの名前value
String - cookieの値domain
String - cookieのドメインhostOnly
String - cookieがホストのみのcookieかどうかpath
String - cookieのパスsecure
Boolean - cookieがセキュアとマークされているかどうかhttpOnly
Boolean - HTTPのみとしてcookieがマークされているかどうかsession
Boolean - cookieがセッションcookieまたは有効期限付きの永続cookieかどうかexpirationDate
Double (オプション) -
cookieの有効期限をUNIX時間で何秒かを示します。セッションcookiesは提供されません。
ses.cookies.set(details, callback)
details
Objecturl
String -url
に関連付けられているcookiesを取得します。name
String - cookieの名前。省略した場合、既定では空です。value
String - cookieの名前。省略した場合、既定では空です。domain
String - cookieのドメイン。省略した場合、既定では空です。path
String - cookieのパス。 省略した場合、既定では空です。secure
Boolean - cookieをセキュアとしてマークする必要があるかどうか。既定ではfalseです。session
Boolean - cookieをHTTPのみとしてマークする必要があるかどうか。既定ではfalseです。expirationDate
Double - cookieの有効期限をUNIX時間で何秒か。省略した場合、cookieはセッションcookieになります。
callback
Function
details
でcookieを設定し、完了するとcallback(error)
でcallback
がコールされます。
ses.cookies.remove(url, name, callback)
url
String - cookieに関連付けられているURLname
String - 削除するcookieの名前callback
Function
url
と name
と一致するcookiesを削除し、完了するとcallback
が、callback()
でコールされます。
ses.getCacheSize(callback)
callback
Functionsize
Integer - 使用しているキャッシュサイズバイト数
現在のセッションのキャッシュサイズを返します。
ses.clearCache(callback)
callback
Function - 操作が完了したら、コールされます。
セッションのHTTPキャッシュをクリアします。
ses.clearStorageData([options, ]callback)
options
Object (オプション)origin
String -window.location.origin
の説明で、scheme://host:port
に従うstorages
Array - クリアするストレージの種類で、次を含められます:appcache
、cookies
、filesystem
、indexdb
、local storage
、shadercache
、websql
、serviceworkers
quotas
Array - クリアするクォーターの種類で、次を含められます:temporary
,persistent
,syncable
.
callback
Function - 操作をするとコールされます。
ウェブストレージのデータをクリアします。
ses.flushStorageData()
書き込まれていないDOMStorageデータをディスクに書き込みます。
ses.setProxy(config, callback)
config
ObjectpacScript
String - PACファイルに関連付けらえたURLproxyRules
String - 使用するプロキシを指定するルール
callback
Function - 操作をするとコールされます。
プロキシ設定を設定します。
pacScript
と proxyRules
が一緒に渡されたら、proxyRules
オプションは無視され、pacScript
設定が適用されます。
proxyRules
はつふぃのルールに従います。
proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]
具体例:
http=foopy:80;ftp=foopy2
-http://
URLはfoopy:80
HTTPプロキシを使用し、ftp://
URLはfoopy2:80
HTTPプロキシを使用します。foopy:80
- 全てのURLでfoopy:80
を使用します。foopy:80,bar,direct://
- 全てのURLでfoopy:80
HTTPプロキシを使用し、foopy:80
が提供されていなければbar
を使用し、さらに使えない場合はプロキシを使いません。socks4://foopy
- 全てのURLでSOCKSfoopy:1080
プロキシを使います。http=foopy,socks5://bar.com
- http URLでfoopy
HTTPプロキシを使い、foopy
が提供されていなければ、SOCKS5 proxybar.com
を使います。http=foopy,direct://
- http URLでfoopy
HTTPプロキシを使い、foopy
が提供されていなければ、プロキシを使いません。http=foopy;socks=foopy2
- http URLでfoopy
HTTPプロキシを使い、それ以外のすべてのURLでsocks4://foopy2
を使います。
ses.resolveProxy(url, callback)
url
URLcallback
Function
url
をプロキシ情報で解決します。リクエストが実行された時、callback(proxy)
で callback
がコールされます。
ses.setDownloadPath(path)
path
String - ダウンロード場所
ダウンロードの保存ディレクトリを設定します。既定では、ダウンロードディレクトリは、個別のアプリフォルダー下のDownloads
です。
ses.enableNetworkEmulation(options)
options
Objectoffline
Boolean - ネットワーク停止を再現するかどうかlatency
Double - RTT ms秒downloadThroughput
Double - Bpsでのダウンロード割合uploadThroughput
Double - Bpsでのアップロード割合
再現ネットワークは、session
用の設定を付与します。
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
latency: 500,
downloadThroughput: 6400,
uploadThroughput: 6400
})
// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({offline: true})
ses.disableNetworkEmulation()
session
ですでに有効になっているネットワークエミュレーションを無効化します。オリジナルのネットワーク設定にリセットします。
ses.setCertificateVerifyProc(proc)
proc
Function
session
の証明書検証ロジックを設定し、サーバー証明書確認がリクエストされた時、proc(hostname, certificate, callback)
でproc
がコールされます。callback(true)
がコールされると証明書を受け入れ、callback(false)
がコールされると拒否します。
Calling setCertificateVerifyProc(null)
をコールして、既定の証明書検証ロジックに戻します。
myWindow.webContents.session.setCertificateVerifyProc(function (hostname, cert, callback) {
callback(hostname === 'github.com')
})
ses.webRequest
webRequest
APIセットをインターセプトし、そのライフタイムの様々な段階でリクエストの内容を変更できます。
APIのイベントが発生したとき、それぞれのAPIはオプションでfilter
と listener
を受け入れ、listener(details)
でlistener
がコールされ、details
はリクエストを説明するオブジェクトです。listener
にnull
が渡されるとイベントの購読をやめます。
filter
はurls
プロパティを持つオブジェクトで、URLパターンにマッチしないリクエストを除外するのに使われるURLパターンの配列です。filter
を省略した場合、全てのリクエストにマッチします。
いくつかのイベントでcallback
でlistener
に渡され、listener
が動作するとき、response
オブジェクトでコールされる必要があります。
// Modify the user agent for all requests to the following urls.
var filter = {
urls: ['https://*.github.com/*', '*://electron.github.io']
}
session.defaultSession.webRequest.onBeforeSendHeaders(filter, function (details, callback) {
details.requestHeaders['User-Agent'] = 'MyAgent'
callback({cancel: false, requestHeaders: details.requestHeaders})
})
ses.webRequest.onBeforeRequest([filter, ]listener)
filter
Objectlistener
Function
リクエストが発生しようとしている時、listener(details, callback)
でlistener
がコールされます。
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleuploadData
Array (オプション)callback
Function
uploadData
は data
オブジェクトの配列です。
data
Objectbytes
Buffer - 送信されるコンテンツfile
String - アップロードされるファイルパス
callback
はresponse
オブジェクトでコールされる必要があります:
response
Objectcancel
Boolean (オプション)redirectURL
String (オプション) - オリジナルリクエストが送信もしくは完了するのを中断し、代わりに付与したURLにリダイレクトします。
ses.webRequest.onBeforeSendHeaders([filter, ]listener)
filter
Objectlistener
Function
リクエストヘッダーが提供されれば、HTTPリクエストが送信される前に、listener(details, callback)
でlistener
がコールされます。TCP接続がサーバーに対して行われた後に発生することがありますが、HTTPデータは送信前です。
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublerequestHeaders
Object
callback
Function
The callback
has to be called with an response
object:
response
Objectcancel
Boolean (オプション)requestHeaders
Object (オプション) - 付与されると、リクエストはそれらのヘッダーで作成されます。
ses.webRequest.onSendHeaders([filter, ]listener)
filter
Objectlistener
Function
サーバーにリクエストを送信しようする直前にlistener(details)
で、listener
がコールされます。前回のonBeforeSendHeaders
レスポンスの変更箇所は、このリスナーが起動した時点で表示されます。
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublerequestHeaders
Object
ses.webRequest.onHeadersReceived([filter,] listener)
filter
Objectlistener
Function
リクエストのHTTPレスポンスヘッダーを受信したとき、listener
はlistener(details, callback)
でコールされます。
details
Objectid
Stringurl
Stringmethod
StringresourceType
Stringtimestamp
DoublestatusLine
StringstatusCode
IntegerresponseHeaders
Object
callback
Function
callback
はresponse
オブジェクトでコールされる必要があります:
response
Objectcancel
BooleanresponseHeaders
Object (オプション) - 付与されていると、これらのヘッダーでサーバーはレスポンスしたと仮定します。
ses.webRequest.onResponseStarted([filter, ]listener)
filter
Objectlistener
Function
レスポンスボディの最初のバイトを受信したとき、listener
はlistener(details)
でコールされます。HTTPリクエストでは、ステータス行とレスポンスヘッダーを意味します。
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleresponseHeaders
ObjectfromCache
Boolean -ディスクキャッシュから取得したレスポンスかどうかを示しますstatusCode
IntegerstatusLine
String
ses.webRequest.onBeforeRedirect([filter, ]listener)
filter
Objectlistener
Function
サーバーがリダイレクトを開始しはじめたとき、listener(details)
でlistener
がコールされます。
details
Objectid
Stringurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleredirectURL
StringstatusCode
Integerip
String (オプション) - 実際にリクエストが送信されるサーバーIPアドレスfromCache
BooleanresponseHeaders
Object
ses.webRequest.onCompleted([filter, ]listener)
filter
Objectlistener
Function
リクエスト完了時、listener
がlistener(details)
でコールされます。
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleresponseHeaders
ObjectfromCache
BooleanstatusCode
IntegerstatusLine
String
ses.webRequest.onErrorOccurred([filter, ]listener)
filter
Objectlistener
Function
エラー発生時、 listener(details)
でlistener
がコールされます。
details
Objectid
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublefromCache
Booleanerror
String - エラーの説明