설명
chrome.storage API를 사용하여 사용자 데이터의 변경사항을 저장, 검색, 추적합니다.
권한
storage개요
Storage API는 사용자 데이터와 상태를 유지하는 확장 프로그램별 방법을 제공합니다. 웹 플랫폼의 스토리지 API (IndexedDB 및 Storage)와 유사하지만 확장 프로그램의 스토리지 요구사항을 충족하도록 설계되었습니다. 다음은 몇 가지 주요 기능입니다.
- 확장 프로그램 서비스 워커 및 콘텐츠 스크립트를 포함한 모든 확장 프로그램 컨텍스트는 Storage API에 액세스할 수 있습니다.
- 직렬화 가능한 JSON 값은 객체 속성으로 저장됩니다.
- Storage API는 일괄 읽기 및 쓰기 작업과 비동기식입니다.
- 사용자가 캐시와 방문 기록을 지우더라도 데이터는 유지됩니다.
- 저장된 설정은 분할 시크릿 모드를 사용해도 유지됩니다.
- 엔터프라이즈 정책을 위한 독점적인 읽기 전용 관리형 스토리지 영역이 포함됩니다.
확장 프로그램이 일부 컨텍스트 (팝업 및 기타 HTML 페이지)에서 [Storage][mdn-storage] 인터페이스 (window.localStorage에서 액세스 가능)를 사용할 수 있지만 다음과 같은 이유로 권장되지 않습니다.
- 확장 프로그램의 서비스 워커가
Storage에 액세스할 수 없습니다. - 콘텐츠 스크립트는 호스트 페이지와 스토리지를 공유합니다.
Storage인터페이스를 사용하여 저장된 데이터는 사용자가 방문 기록을 삭제하면 삭제됩니다.
Web Storage API에서 서비스 워커에서 확장 스토리지 API로 데이터를 이동하려면 다음 안내를 따르세요.
- 전환 루틴과 [
onMessage][on-message] 핸들러를 사용하여 오프스크린 문서를 만듭니다. - 오프스크린 문서에 전환 루틴을 추가합니다.
- 확장 프로그램 서비스 워커에서
chrome.storage에서 데이터를 확인합니다. - 데이터를 찾을 수 없는 경우 오프스크린 문서를 [생성][create-offscreen] 하고 [
sendMessage()][send-message] 를 호출하여 전환 루틴을 시작합니다. - 오프스크린 문서의
onMessage핸들러 내에서 변환 루틴을 호출합니다.
확장 프로그램에서 Web Storage API가 작동하는 방식에도 약간의 미묘한 차이가 있습니다. 자세한 내용은 [저장소 및 쿠키][storage-and-cookies] 도움말을 참고하세요.
보관 영역
Storage API는 다음 4개의 버킷 ('저장 영역')으로 나뉩니다.
storage.local- 데이터는 로컬에 저장되며 확장 프로그램이 삭제되면 삭제됩니다. 할당량 제한은 약 10MB이지만
"unlimitedStorage"권한을 요청하여 늘릴 수 있습니다. 더 많은 양의 데이터를 저장하려면 BigQuery를 사용하는 것이 좋습니다.
storage.sync- 동기화가 사용 설정되면 사용자가 로그인한 모든 Chrome 브라우저에 데이터가 동기화됩니다. 사용 중지하면
storage.local처럼 작동합니다. Chrome은 브라우저가 오프라인일 때 데이터를 로컬에 저장하고 다시 온라인 상태가 되면 동기화를 재개합니다. 할당량 제한은 약 100KB이며 항목당 8KB입니다. 동기화된 브라우저에서 사용자 설정을 유지하기 위해 이 기능을 사용해 보세요.
- storage.session
- 브라우저 세션 동안 메모리에 데이터를 보관합니다. 기본적으로 콘텐츠 스크립트에 노출되지 않지만
chrome.storage.session.setAccessLevel()를 설정하여 이 동작을 변경할 수 있습니다. 할당량 제한은 약 10MB입니다. 서비스 워커 실행 시 전역 변수를 저장하는 데 사용할 수 있습니다.
- storage.managed
- 관리자는 스키마 및 엔터프라이즈 정책을 사용하여 관리 환경에서 지원되는 확장 프로그램의 설정을 구성할 수 있습니다. 이 저장공간은 읽기 전용입니다.
매니페스트
저장소 API를 사용하려면 확장 프로그램 매니페스트에서 "storage" 권한을 선언합니다. 예를 들면 다음과 같습니다.
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
사용
다음 샘플은 local, sync, session 저장소 영역을 보여줍니다.
storage.local
chrome.storage.local.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.local.get(["key"]).then((result) => {
console.log("Value currently is " + result.key);
});
storage.sync
chrome.storage.sync.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.sync.get(["key"]).then((result) => {
console.log("Value currently is " + result.key);
});
storage.session
chrome.storage.session.set({ key: value }).then(() => {
console.log("Value was set");
});
chrome.storage.session.get(["key"]).then((result) => {
console.log("Value currently is " + result.key);
});
managed 저장소 영역에 관한 자세한 내용은 저장소 영역의 매니페스트를 참고하세요.
스토리지 및 제한 한도
Storage API에 추가하는 것을 대형 트럭에 넣는 것으로 생각하지 마세요. 스토리지에 추가하는 것은 파이프에 무언가를 넣는 것과 같습니다. 파이프에 이미 머티리얼이 있을 수 있으며 파이프가 채워질 수도 있습니다. 스토리지에 추가한 시점과 실제로 기록되는 시점 사이의 지연 시간을 항상 가정하세요.
저장용량 영역 한도 및 한도 초과 시 발생하는 상황에 관한 자세한 내용은 sync, local, session의 할당량 정보를 참고하세요.
사용 사례
다음 섹션에서는 Storage API의 일반적인 사용 사례를 보여줍니다.
스토리지 업데이트에 대한 동기식 응답
onChanged 이벤트에 리스너를 추가하면 스토리지의 변경사항을 추적할 수 있습니다. 스토리지에 변경사항이 있으면 해당 이벤트가 실행됩니다. 샘플 코드는 다음 변경사항을 수신 대기합니다.
background.js:
chrome.storage.onChanged.addListener((changes, namespace) => {
for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
console.log(
`Storage key "${key}" in namespace "${namespace}" changed.`,
`Old value was "${oldValue}", new value is "${newValue}".`
);
}
});
이 아이디어를 더욱 발전시킬 수 있습니다. 이 예에는 사용자가 '디버그 모드'를 전환할 수 있는 옵션 페이지가 있습니다(구현은 여기에 표시되지 않음). 옵션 페이지는 새 설정을 즉시 storage.sync에 저장하며, 서비스 워커는 storage.onChanged를 사용하여 가능한 한 빨리 설정을 적용합니다.
options.html:
<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
<label for="debug">
<input type="checkbox" name="debug" id="debug">
Enable debug mode
</label>
</form>
options.js:
// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");
// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
options.debug = event.target.checked;
chrome.storage.sync.set({ options });
});
// Initialize the form with the user's option settings
const data = await chrome.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);
background.js:
function setDebugMode() { /* ... */ }
// Watch for changes to the user's options & apply them
chrome.storage.onChanged.addListener((changes, area) => {
if (area === 'sync' && changes.options?.newValue) {
const debugMode = Boolean(changes.options.newValue.debug);
console.log('enable debug mode?', debugMode);
setDebugMode(debugMode);
}
});
스토리지에서 비동기식 미리 로드
서비스 워커가 항상 실행되는 것은 아니므로 Manifest V3 확장 프로그램이 이벤트 핸들러를 실행하기 전에 저장소에서 데이터를 비동기식으로 로드해야 하는 경우가 있습니다. 이를 위해 다음 스니펫은 로직을 실행하기 전에 storageCache 전역이 채워질 때까지 기다리는 비동기 action.onClicked 이벤트 핸들러를 사용합니다.
background.js:
// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = chrome.storage.sync.get().then((items) => {
// Copy the data retrieved from storage into storageCache.
Object.assign(storageCache, items);
});
chrome.action.onClicked.addListener(async (tab) => {
try {
await initStorageCache;
} catch (e) {
// Handle error that occurred during storage initialization.
}
// Normal action handler logic.
storageCache.count++;
storageCache.lastTabId = tab.id;
chrome.storage.sync.set(storageCache);
});
확장 프로그램 예
Storage API의 다른 데모를 보려면 다음 예시를 살펴보세요.
유형
AccessLevel
저장소 영역의 액세스 수준입니다.
enum
"TRUSTED_CONTEXTS"
확장 프로그램 자체에서 발생한 컨텍스트를 지정합니다.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
확장 프로그램 외부에서 발생한 컨텍스트를 지정합니다.
StorageArea
속성
-
onChanged
이벤트<functionvoid>
Chrome 73 이상하나 이상의 항목이 변경되면 실행됩니다.
onChanged.addListener함수는 다음과 같습니다.(callback: function)=> {...}-
콜백
기능
callback매개변수는 다음과 같습니다.(changes: object)=>void
-
변경사항
객체
-
-
-
삭제
void
프로미스저장소에서 모든 항목을 삭제합니다.
clear함수는 다음과 같습니다.(callback?: function)=> {...}-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.()=>void
-
returns
Promise<void>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
get
void
프로미스저장소에서 하나 이상의 항목을 가져옵니다.
get함수는 다음과 같습니다.(keys?: string|string[]|object,callback?: function)=> {...}-
키
string|string[]|object optional
가져올 단일 키, 가져올 키 목록, 기본값을 지정하는 사전 (객체 설명 참조) 빈 목록이나 객체는 빈 결과 객체를 반환합니다.
null를 전달하여 스토리지의 전체 콘텐츠를 가져옵니다. -
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(items: object)=>void
-
items
객체
키-값 매핑에 항목이 있는 객체입니다.
-
-
returns
Promise<object>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
getBytesInUse
void
프로미스하나 이상의 항목에서 사용 중인 공간의 양 (바이트)을 가져옵니다.
getBytesInUse함수는 다음과 같습니다.(keys?: string|string[],callback?: function)=> {...}-
키
string|string[] optional
총 사용량을 가져올 단일 키 또는 키 목록입니다. 빈 목록은 0을 반환합니다.
null를 전달하여 모든 스토리지의 총 사용량을 가져옵니다. -
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(bytesInUse: number)=>void
-
bytesInUse
숫자
저장소에서 사용 중인 공간의 크기(바이트)입니다.
-
-
returns
프로미스<number>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
제거
void
프로미스저장소에서 하나 이상의 항목을 삭제합니다.
remove함수는 다음과 같습니다.(keys: string|string[],callback?: function)=> {...}-
키
문자열|string[]
삭제할 항목의 단일 키 또는 키 목록입니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.()=>void
-
returns
Promise<void>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
set
void
프로미스여러 항목을 설정합니다.
set함수는 다음과 같습니다.(items: object,callback?: function)=> {...}-
items
객체
저장용량을 업데이트할 각 키-값 쌍을 제공하는 객체입니다. 스토리지의 다른 키-값 쌍은 영향을 받지 않습니다.
숫자와 같은 기본 값은 예상대로 직렬화됩니다.
typeof"object"및"function"가 있는 값은 일반적으로{}로 직렬화됩니다. 단,Array(예상대로 직렬화됨),Date및Regex(String표현을 사용하여 직렬화됨)는 예외입니다. -
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.()=>void
-
returns
Promise<void>
Chrome 88 이상프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
setAccessLevel
void
Promise Chrome 102 이상저장소 영역에 원하는 액세스 수준을 설정합니다. 기본값은 신뢰할 수 있는 컨텍스트만입니다.
setAccessLevel함수는 다음과 같습니다.(accessOptions: object,callback?: function)=> {...}-
accessOptions
객체
-
accessLevel
저장소 영역의 액세스 수준입니다.
-
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.()=>void
-
returns
Promise<void>
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
StorageChange
속성
-
newValue
모든 선택사항
새 값이 있는 경우 항목의 새 값입니다.
-
oldValue
모든 선택사항
항목의 이전 값입니다(이전 값이 있는 경우).
속성
local
local 스토리지 영역에 있는 항목은 각 머신의 로컬입니다.
유형
StorageArea객체(&O)
속성
-
QUOTA_BYTES
10485760
로컬 저장소에 저장할 수 있는 최대 데이터 양 (바이트)으로, 모든 값과 모든 키의 길이를 JSON으로 문자열화하여 측정합니다. 확장 프로그램에
unlimitedStorage권한이 있는 경우 이 값은 무시됩니다. 이 한도를 초과하게 하는 업데이트는 즉시 실패하고 콜백을 사용할 때runtime.lastError를 설정하고, async/await를 사용하는 경우 거부된 Promise를 설정합니다.
managed
managed 저장용량 영역의 항목은 도메인 관리자가 구성한 엔터프라이즈 정책에 의해 설정되며 확장 프로그램에서 읽기 전용입니다. 이 네임스페이스를 수정하려고 하면 오류가 발생합니다. 정책 구성에 관한 자세한 내용은 저장소 영역의 매니페스트를 참고하세요.
유형
session
session 스토리지 영역의 항목은 메모리에 저장되며 디스크에 유지되지 않습니다.
유형
StorageArea객체(&O)
속성
-
QUOTA_BYTES
10485760
모든 값과 키의 동적으로 할당된 메모리 사용량을 추정하여 측정한 메모리에 저장할 수 있는 최대 데이터 양 (바이트)입니다. 이 한도를 초과하게 하는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
runtime.lastError를 설정합니다.
sync
sync 저장용량 영역에 있는 항목은 Chrome 동기화를 사용하여 동기화됩니다.
유형
StorageArea객체(&O)
속성
-
MAX_ITEMS
512
동기화 저장소에 저장할 수 있는 최대 항목 수입니다. 이 한도를 초과하는 업데이트는 즉시 실패하며 콜백을 사용하거나 프로미스를 거부할 때
runtime.lastError를 설정합니다. -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
지원 중단됨storage.sync API에 지속 쓰기 작업 할당량이 더 이상 적용되지 않습니다.
-
MAX_WRITE_OPERATIONS_PER_HOUR
1800
매시간 수행할 수 있는 최대
set,remove또는clear작업 수입니다. 2초마다 1회로, 단기적으로 높은 분당 쓰기 한도보다 낮은 상한선입니다.이 한도를 초과하게 하는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
runtime.lastError를 설정합니다. -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
1분마다 수행할 수 있는 최대
set,remove또는clear작업 수입니다. 이는 초당 2회이므로 단기간에 시간당 쓰기보다 더 높은 처리량을 제공합니다.이 한도를 초과하게 하는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
runtime.lastError를 설정합니다. -
QUOTA_BYTES
102400
모든 값과 모든 키 길이의 JSON 문자열화로 측정한 동기화 스토리지에 저장할 수 있는 데이터의 최대 총량 (바이트)입니다. 이 한도를 초과하게 하는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
runtime.lastError를 설정합니다. -
QUOTA_BYTES_PER_ITEM
8192
동기 저장에 있는 각 개별 항목의 최대 크기 (바이트)로, 값 및 키 길이의 JSON 문자열화로 측정됩니다. 이 한도보다 큰 항목이 포함된 업데이트는 즉시 실패하며, 콜백을 사용하거나 프로미스가 거부될 때
runtime.lastError를 설정합니다.
이벤트
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
하나 이상의 항목이 변경되면 실행됩니다.
매개변수
-
콜백
기능
callback매개변수는 다음과 같습니다.(changes: object,areaName: string)=>void
-
변경사항
객체
-
areaName
문자열
-