Comandos de Armazenamento (Storage)
Os comandos de armazenamento fornecem gerenciamento abrangente do armazenamento do navegador, incluindo cookies, localStorage, sessionStorage e IndexedDB.
Visão Geral
O módulo de comandos de armazenamento permite o gerenciamento de todos os mecanismos de armazenamento do navegador, fornecendo funcionalidade para persistência e recuperação de dados.
pydoll.commands.storage_commands
StorageCommands
A class for interacting with browser storage using Chrome DevTools Protocol (CDP).
The Storage domain of CDP allows managing various types of browser storage, including: - Cookies - Cache Storage - IndexedDB - Web Storage (localStorage/sessionStorage) - Shared Storage - Storage Buckets - Trust Tokens - Interest Groups - Attribution Reporting
This class provides static methods that generate CDP commands to manage these types of storage without the need for traditional webdrivers.
clear_cookies
staticmethod
Generates a command to clear all browser cookies.
| PARAMETER | DESCRIPTION |
|---|---|
browser_context_id
|
Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ClearCookiesCommand
|
The CDP command to clear all cookies.
TYPE:
|
clear_data_for_origin
staticmethod
Generates a command to clear storage data for a specific origin.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com").
TYPE:
|
storage_types
|
Comma-separated list of storage types to clear. Possible values include: "cookies", "local_storage", "indexeddb", "cache_storage", etc. Use "all" to clear all types.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ClearDataForOriginCommand
|
The CDP command to clear data for the specified origin. |
clear_data_for_storage_key
staticmethod
Generates a command to clear data for a specific storage key.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key for which to clear data. Unlike origin, a storage key is a more specific identifier that may include partition isolation.
TYPE:
|
storage_types
|
Comma-separated list of storage types to clear. Possible values include: "cookies", "local_storage", "indexeddb", "cache_storage", etc. Use "all" to clear all types.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ClearDataForStorageKeyCommand
|
The CDP command to clear data for the specified storage key. |
get_cookies
staticmethod
Generates a command to get all browser cookies.
| PARAMETER | DESCRIPTION |
|---|---|
browser_context_id
|
Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
GetCookiesCommand
|
The CDP command to get all cookies, which will return an array of Cookie objects.
TYPE:
|
get_storage_key_for_frame
staticmethod
Generates a command to get the storage key for a specific frame.
Storage keys are used to isolate data between different origins or partitions in the browser.
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
The ID of the frame for which to get the storage key.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
GetStorageKeyForFrameCommand
|
The CDP command to get the storage key for the specified frame. |
get_usage_and_quota
staticmethod
Generates a command to get storage usage and quota information for an origin.
Useful for monitoring or debugging storage consumption of a site.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") for which to get information.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
GetUsageAndQuotaCommand
|
The CDP command that will return: - usage: Storage usage in bytes - quota: Storage quota in bytes - usageBreakdown: Breakdown of usage by storage type - overrideActive: Whether there is an active quota override
TYPE:
|
set_cookies
staticmethod
Generates a command to set browser cookies.
| PARAMETER | DESCRIPTION |
|---|---|
cookies
|
list of Cookie objects to set.
TYPE:
|
browser_context_id
|
Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetCookiesCommand
|
The CDP command to set the specified cookies.
TYPE:
|
set_protected_audience_k_anonymity
staticmethod
Generates a command to set K-anonymity for protected audience.
This command is used to configure anonymity in privacy-preserving advertising systems (part of Google's Privacy Sandbox).
| PARAMETER | DESCRIPTION |
|---|---|
owner
|
Owner of the K-anonymity configuration.
TYPE:
|
name
|
Name of the K-anonymity configuration.
TYPE:
|
hashes
|
list of hashes for the configuration.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetProtectedAudienceKAnonymityCommand
|
The CDP command to set protected audience K-anonymity. |
track_cache_storage_for_origin
staticmethod
Generates a command to register an origin to receive notifications about changes to its Cache Storage.
Cache Storage is primarily used by Service Workers to store resources for offline use.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
TrackCacheStorageForOriginCommand
|
The CDP command to register monitoring of the origin's Cache Storage. |
track_cache_storage_for_storage_key
staticmethod
Generates a command to register a storage key to receive notifications about changes to its Cache Storage.
Similar to track_cache_storage_for_origin, but uses the storage key for more precise isolation.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
TrackCacheStorageForStorageKeyCommand
|
The CDP command to register monitoring of the key's Cache Storage. |
track_indexed_db_for_origin
staticmethod
Generates a command to register an origin to receive notifications about changes to its IndexedDB.
IndexedDB is a NoSQL database system in the browser for storing large amounts of structured data.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
TrackIndexedDBForOriginCommand
|
The CDP command to register monitoring of the origin's IndexedDB. |
track_indexed_db_for_storage_key
staticmethod
Generates a command to register a storage key to receive notifications about changes to its IndexedDB.
Similar to track_indexed_db_for_origin, but uses the storage key for more precise isolation.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
TrackIndexedDBForStorageKeyCommand
|
The CDP command to register monitoring of the key's IndexedDB. |
untrack_cache_storage_for_origin
staticmethod
Generates a command to unregister an origin from receiving notifications about changes to its Cache Storage.
Use this method to stop monitoring Cache Storage after using track_cache_storage_for_origin.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
UntrackCacheStorageForOriginCommand
|
The CDP command to cancel monitoring of the origin's Cache Storage. |
untrack_cache_storage_for_storage_key
staticmethod
Generates a command to unregister a storage key from receiving notifications about changes to its Cache Storage.
Use this method to stop monitoring Cache Storage after using track_cache_storage_for_storage_key.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
UntrackCacheStorageForStorageKeyCommand
|
The CDP command to cancel monitoring of the key's Cache Storage. |
untrack_indexed_db_for_origin
staticmethod
Generates a command to unregister an origin from receiving notifications about changes to its IndexedDB.
Use this method to stop monitoring IndexedDB after using track_indexed_db_for_origin.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
UntrackIndexedDBForOriginCommand
|
The CDP command to cancel monitoring of the origin's IndexedDB. |
untrack_indexed_db_for_storage_key
staticmethod
Generates a command to unregister a storage key from receiving notifications about changes to its IndexedDB.
Use this method to stop monitoring IndexedDB after using track_indexed_db_for_storage_key.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
UntrackIndexedDBForStorageKeyCommand
|
The CDP command to cancel monitoring of the key's IndexedDB. |
clear_shared_storage_entries
staticmethod
Generates a command to clear all Shared Storage entries for a specific origin.
Shared Storage is an experimental API that allows cross-origin shared storage with privacy protections.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage to clear.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ClearSharedStorageEntriesCommand
|
The CDP command to clear the Shared Storage entries. |
clear_trust_tokens
staticmethod
Generates a command to remove all Trust Tokens issued by the specified origin.
Trust Tokens are an experimental API for combating fraud while preserving user privacy. This command keeps other stored data, including the issuer's redemption records, intact.
| PARAMETER | DESCRIPTION |
|---|---|
issuer_origin
|
The issuer origin of the tokens to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ClearTrustTokensCommand
|
The CDP command to clear Trust Tokens, which will return: - didDeleteTokens: True if any tokens were deleted, False otherwise.
TYPE:
|
delete_shared_storage_entry
staticmethod
Generates a command to delete a specific Shared Storage entry.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
key
|
The key of the entry to delete.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DeleteSharedStorageEntryCommand
|
The CDP command to delete the Shared Storage entry. |
delete_storage_bucket
staticmethod
Generates a command to delete a Storage Bucket with the specified key and name.
Storage Buckets are an experimental API for managing storage data with greater granularity and expiration control.
| PARAMETER | DESCRIPTION |
|---|---|
bucket
|
A StorageBucket object containing the storageKey and name of the bucket to delete.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DeleteStorageBucketCommand
|
The CDP command to delete the Storage Bucket. |
get_affected_urls_for_third_party_cookie_metadata
staticmethod
Generates a command to get the list of URLs from a page and its embedded resources that match existing grace period URL pattern rules.
This command is useful for monitoring which URLs would be affected by the Privacy Sandbox's third-party cookie policies.
| PARAMETER | DESCRIPTION |
|---|---|
first_party_url
|
The URL of the page being visited (first-party).
TYPE:
|
third_party_urls
|
Optional list of embedded third-party resource URLs.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
GetAffectedUrlsForThirdPartyCookieMetadataCommand
|
The CDP command to get URLs affected by third-party cookie metadata. |
get_interest_group_details
staticmethod
Generates a command to get details of a specific interest group.
Interest Groups are part of the FLEDGE/Protected Audience API for privacy-preserving advertising, enabling in-browser ad auctions.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the interest group.
TYPE:
|
name
|
The name of the interest group.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
GetInterestGroupDetailsCommand
|
The CDP command to get interest group details. |
get_related_website_sets
staticmethod
Generates a command to get related website sets.
Related Website Sets are an API that allows sites under the same entity to share some data, despite third-party cookie restrictions.
| RETURNS | DESCRIPTION |
|---|---|
GetRelatedWebsiteSetsCommand
|
The CDP command to get related website sets. |
get_shared_storage_entries
staticmethod
Generates a command to get all Shared Storage entries for an origin.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
GetSharedStorageEntriesCommand
|
The CDP command to get the Shared Storage entries. |
get_shared_storage_metadata
staticmethod
Generates a command to get Shared Storage metadata for an origin.
Metadata includes information such as usage, budget, and creation time.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
GetSharedStorageMetadataCommand
|
The CDP command to get Shared Storage metadata. |
get_trust_tokens
staticmethod
Generates a command to get all available Trust Tokens.
| RETURNS | DESCRIPTION |
|---|---|
GetTrustTokensCommand
|
The CDP command to get Trust Tokens, which will return pairs of issuer origin and count of available tokens.
TYPE:
|
override_quota_for_origin
staticmethod
Generates a command to override the storage quota for a specific origin.
This command is useful for storage exhaustion testing or simulating different storage conditions.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The origin for which to override the quota.
TYPE:
|
quota_size
|
The size of the new quota in bytes (optional). If not specified, any existing override will be removed.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OverrideQuotaForOriginCommand
|
The CDP command to override the origin's quota. |
reset_shared_storage_budget
staticmethod
Generates a command to reset the Shared Storage budget for an origin.
Shared Storage uses a budget system to limit the amount of operations or specific operations to preserve user privacy.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ResetSharedStorageBudgetCommand
|
The CDP command to reset the Shared Storage budget. |
run_bounce_tracking_mitigations
staticmethod
Generates a command to run bounce tracking mitigations.
Bounce tracking is a tracking technique that involves redirecting users through intermediate URLs to establish tracking cookies. This command activates protections against this technique.
| RETURNS | DESCRIPTION |
|---|---|
RunBounceTrackingMitigationsCommand
|
The CDP command to run bounce tracking mitigations. |
send_pending_attribution_reports
staticmethod
Generates a command to send pending attribution reports.
Attribution Reporting is an API that allows measuring conversions while preserving user privacy. This command forces sending reports that are waiting to be sent.
| RETURNS | DESCRIPTION |
|---|---|
SendPendingAttributionReportsCommand
|
The CDP command to send pending attribution reports. |
set_attribution_reporting_local_testing_mode
staticmethod
Generates a command to enable or disable local testing mode for Attribution Reporting.
Testing mode makes it easier to develop and test the Attribution Reporting API by removing restrictions like delays and rate limits that would normally apply.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
True to enable local testing mode, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetAttributionReportingLocalTestingModeCommand
|
The CDP command to set Attribution Reporting local testing mode. |
set_attribution_reporting_tracking
staticmethod
Generates a command to enable or disable Attribution Reporting tracking.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetAttributionReportingTrackingCommand
|
The CDP command to set Attribution Reporting tracking. |
set_interest_group_auction_tracking
staticmethod
Generates a command to enable or disable interest group auction tracking.
Interest group auctions are part of the FLEDGE/Protected Audience API and allow for in-browser ad auctions in a privacy-preserving way.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetInterestGroupAuctionTrackingCommand
|
The CDP command to set interest group auction tracking. |
set_interest_group_tracking
staticmethod
Generates a command to enable or disable interest group tracking.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetInterestGroupTrackingCommand
|
The CDP command to set interest group tracking. |
set_shared_storage_entry
staticmethod
Generates a command to set an entry in Shared Storage.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
key
|
The key of the entry to set.
TYPE:
|
value
|
The value of the entry to set.
TYPE:
|
ignore_if_present
|
If True, won't replace an existing entry with the same key.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetSharedStorageEntryCommand
|
The CDP command to set a Shared Storage entry. |
set_shared_storage_tracking
staticmethod
Generates a command to enable or disable Shared Storage tracking.
When enabled, events related to Shared Storage usage will be emitted.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetSharedStorageTrackingCommand
|
The CDP command to set Shared Storage tracking. |
set_storage_bucket_tracking
staticmethod
Generates a command to enable or disable Storage Bucket tracking.
When enabled, events related to changes in storage buckets will be emitted.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key for which to set tracking.
TYPE:
|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SetStorageBucketTrackingCommand
|
The CDP command to set Storage Bucket tracking. |
Uso
Os comandos de armazenamento são usados para gerenciar o armazenamento do navegador em diferentes mecanismos:
from pydoll.commands.storage_commands import get_cookies, set_cookies, clear_data_for_origin
from pydoll.connection.connection_handler import ConnectionHandler
# Obter cookies para um domínio
connection = ConnectionHandler()
cookies = await get_cookies(connection, urls=["https://example.com"])
# Definir um novo cookie
await set_cookies(connection, cookies=[{
"name": "session_id",
"value": "abc123",
"domain": "example.com",
"path": "/",
"httpOnly": True,
"secure": True
}])
# Limpar todo o armazenamento para uma origem
await clear_data_for_origin(
connection,
origin="https://example.com",
storage_types="all"
)
Funcionalidades Principais
O módulo de comandos de armazenamento fornece funções para:
Gerenciamento de Cookies
get_cookies()- Obter cookies por URL ou domínioset_cookies()- Definir novos cookiesdelete_cookies()- Deletar cookies específicosclear_cookies()- Limpar todos os cookies
Local Storage
get_dom_storage_items()- Obter itens do localStorageset_dom_storage_item()- Definir item do localStorageremove_dom_storage_item()- Remover item do localStorageclear_dom_storage()- Limpar localStorage
Session Storage
- Operações de session storage (semelhantes ao localStorage)
- Gerenciamento de dados específicos da sessão
- Armazenamento isolado por aba
IndexedDB
get_database_names()- Obter bancos de dados IndexedDBrequest_database()- Acessar a estrutura do banco de dadosrequest_data()- Consultar dados do banco de dadosclear_object_store()- Limpar object stores
Cache Storage
request_cache_names()- Obter nomes de cacherequest_cached_response()- Obter respostas em cachedelete_cache()- Deletar entradas de cache
Application Cache (Obsoleto)
- Suporte a cache de aplicação legado
- Cache baseado em manifesto
Recursos Avançados
Operações em Massa
# Limpar todos os tipos de armazenamento para múltiplas origens
origins = ["https://example.com", "https://api.example.com"]
for origin in origins:
await clear_data_for_origin(
connection,
origin=origin,
storage_types="cookies,local_storage,session_storage,indexeddb"
)
Cotas de Armazenamento
# Obter informações de uso e cota de armazenamento
quota_info = await get_usage_and_quota(connection, origin="https://example.com")
print(f"Usado: {quota_info.usage} bytes")
print(f"Cota: {quota_info.quota} bytes")
Armazenamento Cross-Origin
# Gerenciar armazenamento entre diferentes origens
await set_cookies(connection, cookies=[{
"name": "cross_site_token",
"value": "token123",
"domain": ".example.com", # Aplica-se a todos os subdomínios
"sameSite": "None",
"secure": True
}])
Tipos de Armazenamento
O módulo suporta vários mecanismos de armazenamento:
| Tipo de Armazenamento | Persistência | Escopo | Capacidade |
|---|---|---|---|
| Cookies | Persistente | Domínio/Caminho | ~4KB por cookie |
| localStorage | Persistente | Origem | ~5-10MB |
| sessionStorage | Sessão | Aba | ~5-10MB |
| IndexedDB | Persistente | Origem | Grande (GB+) |
| Cache API | Persistente | Origem | Grande |
Considerações de Privacidade
Operações de armazenamento podem afetar a privacidade do usuário. Sempre lide com dados de armazenamento de forma responsável e em conformidade com as regulamentações de privacidade.