Class KvApi
- Namespace
- Cloudflare.NET.Accounts.Kv
- Assembly
- Cloudflare.NET.dll
Implementation of Workers KV API operations.
public class KvApi : ApiResource, IKvApi- Inheritance
-
KvApi
- Implements
- Inherited Members
Constructors
KvApi(HttpClient, IOptions<CloudflareApiOptions>, ILoggerFactory)
Initializes a new instance of the KvApi class.
public KvApi(HttpClient httpClient, IOptions<CloudflareApiOptions> options, ILoggerFactory loggerFactory)Parameters
httpClientHttpClientThe HttpClient for making requests.
optionsIOptions<CloudflareApiOptions>The Cloudflare API options containing the account ID.
loggerFactoryILoggerFactoryThe factory to create loggers.
Methods
BulkDeleteAsync(string, IEnumerable<string>, CancellationToken)
Deletes multiple keys in a single request.
public Task<KvBulkDeleteResult> BulkDeleteAsync(string namespaceId, IEnumerable<string> keys, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keysIEnumerable<string>Keys to delete (max 10,000 keys).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<KvBulkDeleteResult>
Result indicating success/failure counts.
Remarks
The request body is a simple JSON array of key names: ["key1", "key2"].
- See Also
BulkGetAsync(string, IEnumerable<string>, CancellationToken)
Retrieves multiple values in a single request.
public Task<IReadOnlyDictionary<string, string?>> BulkGetAsync(string namespaceId, IEnumerable<string> keys, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keysIEnumerable<string>Keys to retrieve (max 100 keys).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyDictionary<string, string>>
Dictionary of key-value pairs (value is null for non-existent keys).
Remarks
The API returns values as a dictionary: { "key1": "value1", "key2": "value2" }. Use BulkGetWithMetadataAsync(string, IEnumerable<string>, CancellationToken) if you need metadata for each key.
- See Also
BulkGetWithMetadataAsync(string, IEnumerable<string>, CancellationToken)
Retrieves multiple values with metadata in a single request.
public Task<IReadOnlyDictionary<string, KvBulkGetItemWithMetadata?>> BulkGetWithMetadataAsync(string namespaceId, IEnumerable<string> keys, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keysIEnumerable<string>Keys to retrieve (max 100 keys).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyDictionary<string, KvBulkGetItemWithMetadata>>
Dictionary of key-value pairs with metadata.
- See Also
BulkWriteAsync(string, IEnumerable<KvBulkWriteItem>, CancellationToken)
Writes multiple key-value pairs in a single request.
public Task<KvBulkWriteResult> BulkWriteAsync(string namespaceId, IEnumerable<KvBulkWriteItem> items, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
itemsIEnumerable<KvBulkWriteItem>Key-value pairs to write (max 10,000 items, 100MB total).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<KvBulkWriteResult>
Result indicating success/failure counts.
Remarks
Existing values and expirations will be overwritten. Check UnsuccessfulKeys and retry if needed.
- See Also
CreateAsync(string, CancellationToken)
Creates a new KV namespace.
public Task<KvNamespace> CreateAsync(string title, CancellationToken cancellationToken = default)Parameters
titlestringThe title for the new namespace. Must be unique per account.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<KvNamespace>
The created namespace.
Exceptions
- CloudflareApiException
Thrown if title already exists (code 10014).
- See Also
DeleteAsync(string, CancellationToken)
Deletes a KV namespace and all its keys.
public Task DeleteAsync(string namespaceId, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID to delete.
cancellationTokenCancellationTokenCancellation token.
Returns
- See Also
DeleteValueAsync(string, string, CancellationToken)
Deletes a key-value pair.
public Task DeleteValueAsync(string namespaceId, string key, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name to delete.
cancellationTokenCancellationTokenCancellation token.
Returns
- See Also
GetAsync(string, CancellationToken)
Gets a specific KV namespace by ID.
public Task<KvNamespace> GetAsync(string namespaceId, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<KvNamespace>
The namespace details.
- See Also
GetMetadataAsync(string, string, CancellationToken)
Reads only the metadata for a key (without retrieving the value).
public Task<JsonElement?> GetMetadataAsync(string namespaceId, string key, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<JsonElement?>
The metadata as JSON, or null if no metadata exists.
- See Also
GetValueAsync(string, string, CancellationToken)
Reads a value by key as a string.
public Task<string?> GetValueAsync(string namespaceId, string key, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Use GetValueWithExpirationAsync(string, string, CancellationToken) if you need the expiration timestamp.
- See Also
GetValueBytesAsync(string, string, CancellationToken)
Reads a value by key as bytes.
public Task<byte[]?> GetValueBytesAsync(string namespaceId, string key, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Use GetValueBytesWithExpirationAsync(string, string, CancellationToken) if you need the expiration timestamp.
- See Also
GetValueBytesWithExpirationAsync(string, string, CancellationToken)
Reads a value by key as bytes, including expiration info.
public Task<KvValueResult?> GetValueBytesWithExpirationAsync(string namespaceId, string key, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<KvValueResult>
The value and expiration, or null if the key doesn't exist.
- See Also
GetValueWithExpirationAsync(string, string, CancellationToken)
Reads a value by key as a string, including expiration info.
public Task<KvStringValueResult?> GetValueWithExpirationAsync(string namespaceId, string key, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<KvStringValueResult>
The value and expiration, or null if the key doesn't exist.
- See Also
ListAllAsync(ListKvNamespacesFilters?, CancellationToken)
Lists all KV namespaces, automatically handling pagination.
public IAsyncEnumerable<KvNamespace> ListAllAsync(ListKvNamespacesFilters? filters = null, CancellationToken cancellationToken = default)Parameters
filtersListKvNamespacesFiltersOptional filters for ordering.
cancellationTokenCancellationTokenCancellation token.
Returns
- IAsyncEnumerable<KvNamespace>
An async enumerable of all namespaces.
ListAllKeysAsync(string, string?, CancellationToken)
Lists all keys in a namespace, automatically handling pagination.
public IAsyncEnumerable<KvKey> ListAllKeysAsync(string namespaceId, string? prefix = null, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
prefixstringOptional prefix filter.
cancellationTokenCancellationTokenCancellation token.
Returns
- IAsyncEnumerable<KvKey>
An async enumerable of all keys.
ListAsync(ListKvNamespacesFilters?, CancellationToken)
Lists KV namespaces in the account.
public Task<PagePaginatedResult<KvNamespace>> ListAsync(ListKvNamespacesFilters? filters = null, CancellationToken cancellationToken = default)Parameters
filtersListKvNamespacesFiltersOptional filters for pagination and ordering.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<PagePaginatedResult<KvNamespace>>
A page of namespaces with pagination info.
- See Also
ListKeysAsync(string, ListKvKeysFilters?, CancellationToken)
Lists keys in a namespace with cursor-based pagination.
public Task<CursorPaginatedResult<KvKey>> ListKeysAsync(string namespaceId, ListKvKeysFilters? filters = null, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
filtersListKvKeysFiltersOptional filters for prefix, limit, and cursor.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<CursorPaginatedResult<KvKey>>
Keys and pagination info (use CursorInfo.Cursor for next page).
- See Also
RenameAsync(string, string, CancellationToken)
Renames a KV namespace.
public Task<KvNamespace> RenameAsync(string namespaceId, string title, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID to rename.
titlestringThe new title for the namespace. Must be unique per account.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<KvNamespace>
The updated namespace with id, title, and supports_url_encoding.
- See Also
WriteValueAsync(string, string, byte[], KvWriteOptions?, CancellationToken)
Writes a binary value.
public Task WriteValueAsync(string namespaceId, string key, byte[] value, KvWriteOptions? options = null, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name (max 512 bytes).
valuebyte[]The value to store (max 25 MiB).
optionsKvWriteOptionsOptional expiration and metadata settings.
cancellationTokenCancellationTokenCancellation token.
Returns
- See Also
WriteValueAsync(string, string, string, KvWriteOptions?, CancellationToken)
Writes a string value.
public Task WriteValueAsync(string namespaceId, string key, string value, KvWriteOptions? options = null, CancellationToken cancellationToken = default)Parameters
namespaceIdstringThe namespace ID.
keystringThe key name (max 512 bytes).
valuestringThe value to store (max 25 MiB).
optionsKvWriteOptionsOptional expiration and metadata settings.
cancellationTokenCancellationTokenCancellation token.
Returns
- See Also