chrome.storage

설명:chrome.storage API를 사용하여 사용자 데이터에 대한 저장, 검색, 변경 추적을 합니다.
유효성:크롬 20부터.
퍼미션:"storage"
컨텐트 스크립트:완벽하게 지원함. 자세히 알아보기
자세히 알아보기:Chrome Apps Office Hours: Chrome Storage APIs (YouTube)
Chrome Apps Office Hours: Storage API Deep Dive (YouTube)

개요

이 API는 확장 프로그램만의 스토리지에 대한 필요성을 충족하기 위해 최적화 되었습니다. localStorage API와 동일한 저장 용량을 제공하며 다음과 같은 주요 차이점이 있습니다.

  • 사용자 데이터는 크롬 동기화와 함께 자동 동기화 됩니다. (storage.sync 사용)
  • 확장 프로그램의 컨텐트 스크립트는 백그라운드 페이지 없이도 사용자 데이터에 직접 액세스 할 수 있습니다.
  • split incognito behavior를 사용하고 있을 때에도 사용자의 확장 프로그램 설정을 지속시킬 수 있습니다.
  • 비동기적으로 대량의 읽고 쓰는 작업을 함으로 localStorage API의 차단과 시리얼보다 속도가 빠릅니다.
  • 사용자 데이터를 객체로 저장합니다. (localStorage API는 문자열(string)로 저장합니다.)
  • 관리자에 의해 엔터프라이즈 정책이 설정되어있고 확장 프로그램이 읽을 수 있습니다. (schemastorage.managed를 사용)

Manifest

스토리지 API를 사용하려면 manifest에 “storage” 퍼미션을 선언해야 합니다.

사용법

확장 프로그램에 사용자 데이터를 저장하기 위해 storage.sync 또는 storage.local을 사용합니다. storage.sync는 사용자가 로그인한 모든 크롬 브라우저에 저장된 데이터가 자동으로 동기화 되도록 합니다. (동기화를 설정한 사용자에게)

크롬이 오프라인일 때, 크롬은 데이터를 로컬에 저장합니다. 온라인 상태가 되면 크롬이 데이터를 동기화합니다. 사용자가 동기화를 비활성화 하더라도 storage.sync는 동작합니다. 이 경우 storage.local도 동일하게 동작합니다.

중요한 사용자 정보를 저장해서는 안됩니다! 스토리지 영역은 암호화 되어있지 않습니다.

storage.managed는 ‘읽기 전용’ 입니다.

스토리지와 스로틀링(throttling) 한도

chrome.storage는 크지 않습니다. 튜브(tubes)가 연속적으로 이어져있는 것과 같습니다. 이것을 이해하지 못하면, 튜브가 가득찰 수 있습니다. 그리고 메시지를 넣으려고 할 때 튜브가 차 있다면, 해당 메시지는 라인에 도달한 후 딜레이 될 것입니다.

storage API의 현재 한도와 초과에 대해, synclocal의 쿼터 정보를 참조해 주세요.

예제

다음 예제는 폼에서 사용자에 의해 저장된 CSS 코드를 확인하고, 그것을 찾아내 저장합니다.

데이터 객체의 변경을 추적하고 싶다면, onChanged 이벤트에 리스너를 추가하면 됩니다. 스토리지에 어떠한 변화라도 생기면 이벤트가 발생합니다. 아래에 저장된 변경사항을 listen하는 샘플코드가 있습니다.

요약

타입
StorageChange
StorageArea
프로퍼티
sync
local
managed
이벤트
onChanged

타입

StorageChange

프로퍼티
any(optional) oldValue 이전값이 있다면, 항목에 이전값이 옵니다.
any(optional) newValue새값이 있다면, 항목에 새값이 옵니다.

StorageArea의 메서드 종류

get

  • 선언: StorageArea.get(string or array of string or object keys, function callback)
  • 설명: 스토리지에서 하나 또는 그 이상의 아이템을 가져옵니다.
파라미터
string or array of string or object(optional) keys값을 가져오는 단일키, 키 리스트, 또는 기본값을 지정하는 딕셔너리(dictionary)가 옵니다. 빈 리스트나 객체는 빈 결과 객체를 리턴합니다. 스토리지의 전체 컨텐츠를 가져오려면 null을 전달합니다.
functioncallback스토리지의 아이템이나 failure(이 경우에는 runtime.lastError가 지정됩니다.)가 콜백됩니다.

callback 파라미터는 다음과 같은 함수여야 합니다.

function(object items) {...};

'items'는 key-value로 맵핑되어 있습니다.

getBytesInUse

  • 선언: StorageArea.getBytesInUse(string or array of string keys, function callback)
  • 설명: 아이템에 의해 사용되는 공간의 크기(바이트)를 가져옵니다.
파라미터
string or array of string(optional) keys단일 키나 키 리스트는 전체 사용량을 가져옵니다. 빈 리스트는 0을 리턴합니다. null은 모든 스토리지의 총 사용량을 가져옵니다.
functioncallback스토리지에서 사용되고 있는 공간의 크기 또는 failure를 콜백합니다.(이 경우에는 runtime.lastError가 지정됩니다.)

callback 파라미터는 다음과 같은 모양의 함수입니다.

function(integer bytesInUse) {...};

'bytesInUse'는 스토리지에서 사용되고 있는 공간의 크기(bytes)입니다.

set

  • 선언: StorageArea.set(object items, function callback)
  • 설명: 여러 아이템을 설정합니다.
파라미터
objectitems객체는 스토리지에 업데이트 할 각 키/밸류의 쌍을 가집니다. 스토리지에 있는 다른 키/밸류는 영향을 받지 않습니다.

Number와 같은 기본 자료형(primitive values)은 예상대로 직렬화(serialize - *상태를 저장하기 위해 byte stream으로 변환하는 것)됩니다. typeof "object""function" 값은 일반적으로 {}로 직렬화됩니다, with the exception of Array (serializes as expected), Date, and Regex (serialize using their String representation).
function(optional) callback성공 또는 실패(runtime.lastError가 지정됨)가 콜백됩니다.

callback 파라미터를 지정한다면 다음과 같은 형태가 되어야 합니다.

function() {...};

remove

  • 선언: StorageArea.remove(string or array of string keys, function callback)
  • 설명: 스토리지에서 하나 또는 그 이상의 아이템을 삭제합니다.
파라미터
string or array of stringkeys아이템을 삭제하기 위해 1개의 키 또는 키의 리스트가 옵니다.
function(optional) callback성공 또는 실패(runtime.lastError가 지정됨)가 콜백됩니다.

callback 파라미터를 지정한다면 다음과 같은 형태가 되어야 합니다.

function() {...};

clear

  • 선언: StorageArea.clear(function callback)
  • 설명: 스토리지의 모든 아이템을 삭제합니다.
파라미터
function (optional) callback성공 또는 실패(runtime.lastError가 지정됨)가 콜백됩니다.

callback 파라미터를 지정한다면 다음과 같은 형태가 되어야 합니다.

function() {...};

StorageArea의 프로퍼티

chrome.storage.sync
‘크롬 동기화’를 사용해 ‘sync‘ 스토리지 영역(area)에 있는 아이템을 동기화합니다.

프로퍼티
102,400QUOTA_BYTESsync 스토리지에 저장될 수 있는 데이터의 최대 양(bytes)을 의미합니다. 모든 값(value)에 모든 키(key)의 길이가 더해져 JSON 문자열화(stringification)를 통해 측정됩니다. 제한된 용량이 초과되면 즉시 실패를 알려주고 runtime.lastError를 설정합니다.
8,192QUOTA_BYTES_PER_ITEMsync 스토리지에 있는 각각의 개별 아이템의 최대 크기(bytes)를 나타냅니다, 해당 아이템의 값(value)과 키(key)의 길이가 더해져 JSON 문자열화(stringification)를 통해 측정됩니다. 이 한계값보다 큰 아이템이 들어가면 즉시 실패를 알려주고 runtime.lastError를 설정합니다.
512MAX_ITEMSsync 스토리지에 저장될 수 있는 아이템의 최대 개수를 의미합니다.이 제한값을 넘어가면 즉시 실패를 알려주고 runtime.lastError을 설정합니다.
1,800MAX_WRITE_OPERATIONS_PER_HOUR시간마다 실행될 수 있는 set, remove, clear 오퍼레이션의 최대 수입니다. 이것은 2초에 1회 실행할 수 있음을 뜻합니다, 분당 쓸 수 있는 것 보다 더 낮은 제한을 두고 있습니다.(a lower ceiling than the short term higher writes-per-minute limit.)

제한된 횟수가 초과되면 즉시 실패를 알려주고 runtime.lastError를 설정합니다.
120MAX_WRITE_OPERATIONS_PER_MINUTE(크롬 버전 40부터.)

'초'마다 실행될 수 있는 set, remove, clear 오퍼레이션의 최대 수입니다. 이것은 초당 2회를 뜻합니다, 시간당 쓸 수 있는 것보다 더 많은 처리량을 제공합니다.

제한된 횟수가 초과되면 즉시 실패를 알려주고 runtime.lastError를 설정합니다.
1,000,000MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE(Deprecated 크롬 버전 40부터.) 이 storage.sync API는 더 이상 쓰기 오퍼레이션 쿼터를 가지고 있지 않습니다.

chrome.storage.local
‘local’ 스토리지 영역에 있는 아이템은 각 머신(machine) 지역(local)에 있습니다.

프로퍼티
5,242,880QUOTA_BYTES로컬 스토리지에 저장할 수 있는 데이터의 최대 양(bytes)입니다. 모든 값(value)과 모든 키(key)를 더한 길이를 JSON 문자열화(stringification)를 통해 측정됩니다. 확장 프로그램이 unlimitedStorage 퍼미션을 가질 경우 이 프로퍼티값은 무시됩니다. 제한된 용량이 초과되면 바로 실패 원인을 업데이트하고 runtime.lastError가 설정됩니다.

chrome.storage.managed
(크롬 33버전부터.) ‘managed’ 스토리지 영역에 있는 아이템이 도메인 관리자에 의해 설정되고 확장 프로그램의 읽기 전용이 됩니다; 이 네임스페이스를 수정하면 에러가 발생합니다.

이벤트

onChanged

하나 또는 그 이상의 아이템이 변경되면 발생합니다.

addListener
chrome.storage.onChanged.addListener(function callback)

프로퍼티
functioncallbackcallback 파라미터는 다음과 같은 함수 형식을 가집니다:

function(object changes, string areaName) {...};

  • changes: Object mapping each key that changed to its corresponding storage.StorageChange for that item.
  • areaName: (크롬 22버전부터.) 스토리지 'sync', 'local', 'managed' 중 변경이 있는 영역