Purge

O módulo azion/purge é a biblioteca da Azion Lib do Real-Time Purge. As funções dele removem URLs, cache keys e expressões wildcard do cache pela Azion API v4, de modo que a requisição seguinte busca a versão atual na origem. Cada função recebe uma lista de strings e retorna um envelope de resposta em vez de lançar uma exceção.

Instale o pacote:

npm install azion

O pacote azion recebe apenas correções de bugs, e a manutenção dele termina em dezembro de 2026.

Todos os exemplos abaixo são módulos ES em TypeScript com await de nível superior, executados no Node.js. Os tipos entram por import type, então o exemplo ainda carrega depois que as anotações de tipo são removidas.

Autenticação

Cada requisição de purge carrega o seu personal token. As funções leem o token da variável de ambiente AZION_TOKEN, e um cliente criado com createClient lê o token do campo token.

Variável	Descrição
`AZION_TOKEN`	Seu personal token da Azion.
`AZION_DEBUG`	Com `true`, ativa o modo de debug.

Para ver onde cada pacote da Azion Lib procura esses valores, consulte Como a Azion Lib funciona.

Envelope de resposta

Toda função retorna um objeto AzionPurgeResponse, { data?, error? }. Em caso de sucesso, data contém um objeto AzionPurge: items, a lista que o purge recebeu, e state. Em caso de falha, error contém { message, operation }, e operation é post purge.

Cada função envia uma requisição para a Azion API v4. A API responde com os itens e a camada que purgou, e o envelope mantém apenas items e state:

Função	Requisição da API	Argumento
purgeURL	`POST /v4/workspace/purge/url`	Uma lista de URLs
purgeCacheKey	`POST /v4/workspace/purge/cachekey`	Uma lista de cache keys
purgeWildCard	`POST /v4/workspace/purge/wildcard`	Uma lista de expressões wildcard

As funções não recebem argumento de camada, e a API informa layer: 'cache' na resposta. Para as camadas e o número de itens que cada tipo de purge aceita, consulte Real-Time Purge.

createClient

Cria um cliente que guarda um token e expõe as três funções de purge como métodos.

TypeScript

01function createClient(config?: Partial<{

02 token: string;

03 options?: AzionClientOptions;

04}>): AzionPurgeClient;

Parâmetro	Tipo	Obrigatório	Descrição
`token`	`string`	Não	Seu personal token da Azion.
`options`	`AzionClientOptions`	Não	Opções do cliente.

Retorna um AzionPurgeClient. Os métodos dele recebem a mesma lista que a função correspondente desta página, sem options. Para registrar no log a resposta que a API retorna, passe { debug: true } para uma função, como faz o exemplo de purgeURL.

Este exemplo cria um cliente e purga uma URL com ele:

TypeScript

01import { createClient } from 'azion/purge';

02import type { AzionPurgeClient, AzionPurgeResponse, AzionPurge } from 'azion/purge';

04const client: AzionPurgeClient = createClient({ token: process.env.AZION_TOKEN, options: { debug: true } });

06const { data: purgeURLResponse, error }: AzionPurgeResponse<AzionPurge> = await client.purgeURL([

07 'http://www.example.com/image.jpg',

08]);

09if (purgeURLResponse) {

10 console.log('Purge successful:', purgeURLResponse);

11} else {

12 console.error('Purge failed', error);

13}

Saída:

Texto

01Purge successful: {

02 items: [ 'http://www.example.com/image.jpg' ],

03 state: 'executed'

04}

purgeURL

Purga uma lista de URLs do cache. Apenas as URLs da lista saem do cache.

function purgeURL(url: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;

Parâmetro	Tipo	Obrigatório	Descrição
`url`	`string[]`	Sim	As URLs a purgar.
`options`	`AzionClientOptions`	Não	Opções da requisição. Com `debug: true`, a função registra no log a resposta que a API retorna.

Retorna data como um objeto AzionPurge com as URLs purgadas em items. Uma URL cujo host não pertence a nenhum domínio da sua conta retorna error; a mensagem está em Erros.

Este exemplo purga uma URL no modo de debug, então a saída começa com a resposta da API:

TypeScript

01import { purgeURL } from 'azion/purge';

02import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

04const url: string[] = ['http://www.example.com/image.jpg'];

05const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeURL(url, { debug: true });

06if (response) {

07 console.log('Purge successful:', response);

08} else {

09 console.error('Purge failed', error);

10}

Saída:

Texto

01Response: {

02 state: 'executed',

03 data: {

04 items: [ 'http://www.example.com/image.jpg' ],

05 layer: 'cache'

06 }

07}

08Purge successful: {

09 items: [ 'http://www.example.com/image.jpg' ],

10 state: 'executed'

11}

purgeCacheKey

Purga uma lista de cache keys do cache. Uma cache key nomeia uma variação de um objeto em cache.

function purgeCacheKey(cacheKey: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;

Parâmetro	Tipo	Obrigatório	Descrição
`cacheKey`	`string[]`	Sim	As cache keys a purgar, sem scheme.
`options`	`AzionClientOptions`	Não	Opções da requisição. Com `debug: true`, a função registra no log a resposta que a API retorna.

Retorna data como um objeto AzionPurge com as keys purgadas em items. Uma key não leva scheme: a forma host/path é aceita, e uma key que começa com um scheme, como http://, é recusada com error. Para o formato de uma key, consulte Cache keys.

Este exemplo purga uma cache key no modo de debug:

TypeScript

01import { purgeCacheKey } from 'azion/purge';

02import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

04const cacheKey: string[] = ['www.example.com/image.jpg'];

05const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeCacheKey(cacheKey, { debug: true });

06if (response) {

07 console.log('Purge successful:', response);

08} else {

09 console.error('Purge failed', error);

10}

Saída:

Texto

01Response: {

02 state: 'executed',

03 data: {

04 items: [ 'www.example.com/image.jpg' ],

05 layer: 'cache'

06 }

07}

08Purge successful: {

09 items: [ 'www.example.com/image.jpg' ],

10 state: 'executed'

11}

purgeWildCard

Purga os objetos em cache que casam com uma expressão wildcard: uma URL com um asterisco (*) no path ou na query string.

function purgeWildCard(wildcard: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;

Parâmetro	Tipo	Obrigatório	Descrição
`wildcard`	`string[]`	Sim	As expressões wildcard a purgar.
`options`	`AzionClientOptions`	Não	Opções da requisição. Com `debug: true`, a função registra no log a resposta que a API retorna.

Retorna data como um objeto AzionPurge com a expressão em items. O tipo recebe uma lista, e o Real-Time Purge aceita uma expressão wildcard por requisição. Para as expressões que ele aceita, consulte Purge por wildcard.

Este exemplo purga todos os objetos em cache sob um prefixo de path:

TypeScript

01import { purgeWildCard } from 'azion/purge';

02import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

04const wildcard: string[] = ['http://www.example.com/images/*'];

05const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeWildCard(wildcard, { debug: true });

06if (response) {

07 console.log('Purge successful:', response);

08} else {

09 console.error('Purge failed', error);

10}

Saída:

Texto

01Response: {

02 state: 'executed',

03 data: {

04 items: [ 'http://www.example.com/images/*' ],

05 layer: 'cache'

06 }

07}

08Purge successful: {

09 items: [ 'http://www.example.com/images/*' ],

10 state: 'executed'

11}

Erros

Um purge recusado retorna error apenas com o status HTTP. O motivo que a API informa, como The Content must be a valid cachekey., não chega ao envelope. error.operation é post purge em todas as funções.

Mensagem	Causa	O que fazer
`Error: HTTP error! Status: 400 - Bad Request`	Uma cache key passada para purgeCacheKey começa com um scheme, como `http://`.	Passe a key sem o scheme, na forma `host/path`.
`Error: HTTP error! Status: 400 - Bad Request`	O host de uma URL passada para purgeURL não pertence a nenhum domínio da sua conta.	Purgue uma URL de um domínio da sua conta.

Para os códigos de erro que a API retorna em cada tipo de purge, consulte Real-Time Purge.

Tipos

O módulo azion/purge exporta estes tipos. Importe-os com import type.

AzionPurgeClient

O objeto que createClient retorna, com um método por tipo de purge. Cada método recebe uma lista.

Método	Argumento	Retorno
`purgeURL`	`urls: string[]`	`Promise<AzionPurgeResponse<AzionPurge>>`
`purgeCacheKey`	`cacheKeys: string[]`	`Promise<AzionPurgeResponse<AzionPurge>>`
`purgeWildCard`	`wildcards: string[]`	`Promise<AzionPurgeResponse<AzionPurge>>`

CreateAzionPurgeClient

O tipo de createClient.

TypeScript

01type CreateAzionPurgeClient = (config?: Partial<{

02 token: string;

03 options?: AzionClientOptions;

04}>) => AzionPurgeClient;

AzionClientOptions

Opções de requisição que toda função recebe em options.

Propriedade	Tipo	Obrigatório	Descrição
`debug`	`boolean`	Não	Registra no log a resposta que a API retorna, quando passado para uma função.
`force`	`boolean`	Não	—

AzionPurgeResponse

O objeto que cada função de purge retorna. Envelope de resposta descreve as formas de sucesso e de falha.

Propriedade	Tipo	Obrigatório	Descrição
`data`	`T`	Não	O resultado do purge, definido em caso de sucesso.
`error`	`{ message: string; operation: string }`	Não	A mensagem de falha e o nome da operação que falhou, definidos em caso de falha.

AzionPurge

O resultado de um purge.

Propriedade	Tipo	Obrigatório	Descrição
`state`	`'executed' \| 'pending'`	Sim	O estado da requisição de purge.
`items`	`string[]`	Sim	As URLs, cache keys ou expressões wildcard que o purge recebeu.

Recursos relacionados

Azion Lib

Todas as bibliotecas da Azion Lib, com o pacote npm a instalar para cada uma.

Client

Um único cliente que alcança as funções de purge junto com os módulos dos outros produtos.

Real-Time Purge

Tipos de purge, camadas, limites de requisição e os erros que a API de purge retorna.

Cache keys

Como a Azion monta a cache key que um purge por cache key atinge.