설명
chrome.storage API를 사용하여 사용자 데이터의 변경사항을 저장, 검색, 추적합니다.
권한
storage개요
Storage API는 사용자 데이터와 상태를 유지하는 확장 프로그램별 방법을 제공합니다. 웹 플랫폼의 스토리지 API (IndexedDB 및 Storage)와 유사하지만 확장 프로그램의 스토리지 요구사항을 충족하도록 설계되었습니다. 다음은 몇 가지 주요 기능입니다.
- 확장 프로그램 서비스 워커 및 콘텐츠 스크립트를 비롯한 모든 확장 프로그램 컨텍스트는 Storage API에 액세스할 수 있습니다.
- JSON 직렬화 가능한 값은 객체 속성으로 저장됩니다.
- Storage API는 일괄 읽기 및 쓰기 작업과 비동기식입니다.
- 사용자가 캐시와 방문 기록을 삭제해도 데이터는 유지됩니다.
- 저장된 설정은 분할 시크릿 모드를 사용하는 경우에도 유지됩니다.
- 엔터프라이즈 정책을 위한 전용 읽기 전용 관리 스토리지 영역이 포함되어 있습니다.
확장 프로그램은 일부 컨텍스트 (팝업 및 기타 HTML 페이지)에서 [Storage][mdn-storage] 인터페이스 (window.localStorage에서 액세스 가능)를 사용할 수 있지만 다음과 같은 이유로 권장되지 않습니다.
- 확장 프로그램의 서비스 워커가
Storage에 액세스할 수 없습니다. - 콘텐츠 스크립트는 호스트 페이지와 스토리지를 공유합니다.
Storage인터페이스를 사용하여 저장된 데이터는 사용자가 방문 기록을 삭제하면 손실됩니다.
서비스 워커에서 웹 저장소 API의 데이터를 확장 프로그램 저장소 API로 이동하려면 다음 단계를 따르세요.
- 전환 루틴과 [
onMessage][on-message] 핸들러가 있는 오프스크린 문서를 만듭니다. - 오프스크린 문서에 변환 루틴을 추가합니다.
- 확장 프로그램 서비스 워커에서 데이터의
chrome.storage를 확인합니다. - 데이터를 찾을 수 없는 경우 오프스크린 문서를 [만들고][create-offscreen] [
sendMessage()][send-message] 를 호출하여 변환 루틴을 시작합니다. - 오프스크린 문서의
onMessage핸들러 내에서 변환 루틴을 호출합니다.
웹 저장소 API가 확장 프로그램에서 작동하는 방식에도 약간의 차이가 있습니다. [저장소 및 쿠키][storage-and-cookies] 도움말에서 자세히 알아보세요.
저장소 영역
Storage API는 다음 4가지 버킷 ('저장소 영역')으로 나뉩니다.
storage.local- 데이터는 로컬에 저장되며 확장 프로그램이 삭제되면 지워집니다. 할당량 제한은 약 10MB이지만
"unlimitedStorage"권한을 요청하여 늘릴 수 있습니다. 대용량 데이터를 저장하는 데 사용하는 것이 좋습니다.
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
저장소 영역의 액세스 수준입니다.
열거형
"TRUSTED_CONTEXTS"
확장 프로그램 자체에서 발생한 컨텍스트를 지정합니다.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
확장 프로그램 외부에서 발생한 컨텍스트를 지정합니다.
StorageArea
속성
-
onChanged
Event<functionvoidvoid>
Chrome 73 이상하나 이상의 항목이 변경될 때 실행됩니다.
onChanged.addListener함수는 다음과 같습니다.(callback: function) => {...}
-
콜백
함수
callback매개변수는 다음과 같습니다.(changes: object) => void
-
변경사항
객체
-
-
-
지우기
void
Promise저장소에서 모든 항목을 삭제합니다.
clear함수는 다음과 같습니다.(callback?: function) => {...}
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
-
returns
Promise<void>
Chrome 88 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
get
void
Promise저장소에서 항목을 하나 이상 가져옵니다.
get함수는 다음과 같습니다.(keys?: string | string[] | object, callback?: function) => {...}
-
키
string | string[] | object 선택사항
가져올 단일 키, 가져올 키 목록 또는 기본값을 지정하는 사전입니다 (객체 설명 참고). 빈 목록이나 객체는 빈 결과 객체를 반환합니다.
null를 전달하여 저장소의 전체 콘텐츠를 가져옵니다. -
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(items: object) => void
-
항목
객체
키-값 매핑에 항목이 있는 객체입니다.
-
-
returns
Promise<object>
Chrome 88 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
getBytesInUse
void
Promise하나 이상의 항목에서 사용 중인 공간 (바이트)을 가져옵니다.
getBytesInUse함수는 다음과 같습니다.(keys?: string | string[], callback?: function) => {...}
-
키
문자열 | string[] 선택사항
총 사용량을 가져올 단일 키 또는 키 목록입니다. 빈 목록은 0을 반환합니다.
null를 전달하여 모든 저장소의 총 사용량을 가져옵니다. -
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(bytesInUse: number) => void
-
bytesInUse
숫자
스토리지에서 사용 중인 공간(단위: 바이트)입니다.
-
-
returns
Promise<number>
Chrome 88 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
getKeys
void
Promise Chrome 130 이상저장소에서 모든 키를 가져옵니다.
getKeys함수는 다음과 같습니다.(callback?: function) => {...}
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(keys: string[]) => void
-
키
문자열[]
저장소에서 읽은 키가 있는 배열입니다.
-
-
returns
Promise<string[]>
Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
삭제
void
Promise저장소에서 하나 이상의 항목을 삭제합니다.
remove함수는 다음과 같습니다.(keys: string | string[], callback?: function) => {...}
-
키
문자열 | 문자열[]
삭제할 항목의 키 하나 또는 키 목록입니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
-
returns
Promise<void>
Chrome 88 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
set
void
Promise여러 항목을 설정합니다.
set함수는 다음과 같습니다.(items: object, callback?: function) => {...}
-
항목
객체
저장소를 업데이트할 각 키-값 쌍을 제공하는 객체입니다. 저장소의 다른 키/값 쌍은 영향을 받지 않습니다.
숫자와 같은 원시 값은 예상대로 직렬화됩니다.
typeof"object"및"function"가 있는 값은 일반적으로{}로 직렬화됩니다. 단,Array(예상대로 직렬화됨),Date,Regex(String표현식을 사용하여 직렬화됨)는 예외입니다. -
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
-
returns
Promise<void>
Chrome 88 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
-
setAccessLevel
void
Promise Chrome 102 이상저장소 영역의 원하는 액세스 수준을 설정합니다. 기본값은 신뢰할 수 있는 컨텍스트만 됩니다.
setAccessLevel함수는 다음과 같습니다.(accessOptions: object, callback?: function) => {...}
-
accessOptions
객체
-
accessLevel
저장소 영역의 액세스 수준입니다.
-
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
-
returns
Promise<void>
Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
-
StorageChange
속성
-
newValue
any 선택사항
새 값이 있는 경우 항목의 새 값입니다.
-
oldValue
any 선택사항
이전 값이 있는 경우 항목의 이전 값입니다.
속성
local
local 저장소 영역의 항목은 각 머신에 로컬로 있습니다.
유형
StorageArea 및 객체
속성
-
QUOTA_BYTES
10485760
모든 값의 JSON 문자열화와 모든 키의 길이를 합산하여 측정한 로컬 저장소에 저장할 수 있는 최대 데이터 양 (바이트)입니다. 확장 프로그램에
unlimitedStorage권한이 있는 경우 이 값은 무시됩니다. 이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하는 경우runtime.lastError를 설정하거나 async/await를 사용하는 경우 거부된 Promise를 설정합니다.
managed
managed 저장소 영역의 항목은 도메인 관리자가 구성한 엔터프라이즈 정책에 의해 설정되며 확장 프로그램에 대해 읽기 전용입니다. 이 네임스페이스를 수정하려고 하면 오류가 발생합니다. 정책 구성에 관한 자세한 내용은 저장소 영역 매니페스트를 참고하세요.
유형
sync
sync 저장소 영역의 항목은 Chrome 동기화를 사용하여 동기화됩니다.
유형
StorageArea 및 객체
속성
-
MAX_ITEMS
512
동기화 저장소에 저장할 수 있는 최대 항목 수입니다. 이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
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
분당 실행할 수 있는 최대
set,remove,clear작업 수입니다. 초당 2회이므로 더 짧은 시간에 시간당 쓰기보다 높은 처리량을 제공합니다.이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
runtime.lastError를 설정합니다. -
QUOTA_BYTES
102400
동기화 저장소에 저장할 수 있는 최대 총 데이터 양 (바이트)으로, 모든 값의 JSON 문자열화와 모든 키의 길이를 합산하여 측정합니다. 이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
runtime.lastError를 설정합니다. -
QUOTA_BYTES_PER_ITEM
8192
동기화 저장소에 있는 각 개별 항목의 최대 크기 (바이트)로, 값의 JSON 문자열화와 키 길이를 합산하여 측정합니다. 이 한도보다 큰 항목이 포함된 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때
runtime.lastError를 설정합니다.
이벤트
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
하나 이상의 항목이 변경될 때 실행됩니다.
매개변수
-
콜백
함수
callback매개변수는 다음과 같습니다.(changes: object, areaName: string) => void
-
변경사항
객체
-
areaName
문자열
-