Políticas de filtro

O filtro escolhe quais mensagens publicadas geram uma entrega para a assinatura. Coloque valores de roteamento no mapa attributes. Um campo event dentro do texto JSON de message não se torna um atributo filtrável.

Um exemplo completo

Esta política aceita pedidos de produção de valor mínimo 100 e menor que 1.000, salvo quando há um atributo test:

{
  "event": ["order.created", "order.paid"],
  "environment": ["production"],
  "amount": [{ "numeric": [">=", 100, "<", 1000] }],
  "test": [{ "exists": false }]
}

Estes atributos de publicação correspondem:

{
  "event": { "type": "String", "value": "order.paid" },
  "environment": { "type": "String", "value": "production" },
  "amount": { "type": "Number", "value": "149.50" }
}

Valores de atributos são strings mesmo com tipo Number. Operandos numéricos do filtro são números JSON. Mantenha as representações distintas.

Alteração nos atributos	Resultado	Motivo
Nenhuma	Corresponde	Todas as condições são satisfeitas.
`event` vira `order.refunded`	Não corresponde	Nenhuma alternativa de evento corresponde.
`amount` vira `1000`	Não corresponde	O limite superior é exclusivo.
Remover `amount`	Não corresponde	Comparações numéricas exigem presença.
Adicionar `test` com valor `false`	Não corresponde	`exists: false` verifica ausência, não valor.
Adicionar atributo `customer` não relacionado	Corresponde	Atributos extras são ignorados.

Como combinar condições

Todos os atributos nomeados devem corresponder: AND entre nomes de atributos. Na lista de um atributo, basta uma alternativa: OR entre alternativas. Dentro de um único operador numeric, todas as comparações devem ser satisfeitas. Nomes e comparações textuais distinguem maiúsculas. Uma política vazia {} aceita todas as mensagens, inclusive sem atributos. Todos os operadores exceto exists: false exigem presença. Atributos ausentes não correspondem a exclusões como anything-but.

Comparações disponíveis

Os exemplos mostram a lista de alternativas de um atributo.

Comparação	Exemplo	Comportamento
String exata	`["critical", "error"]`	Valor igual a uma das strings.
Prefixo	`[{"prefix": "order."}]`	Começa com `order.`.
Sufixo	`[{"suffix": ".failed"}]`	Termina com `.failed`.
Exclusão	`[{"anything-but": ["debug", "trace"]}]`	Valor presente diferente dos itens. Também aceita uma string ou número.
Presença	`[{"exists": true}]`	Atributo existe, inclusive com string vazia.
Ausência	`[{"exists": false}]`	Atributo ausente.
Intervalo numérico	`[{"numeric": [">=", 100, "<", 1000]}]`	Valor numérico que satisfaz ambas as comparações.
Igualdade numérica	`[{"numeric": ["=", 100]}]`	Compara números: `100` e `100.0` correspondem.

Operadores numéricos: =, <, <=, > e >=. Escreva operador e operando; repita pares para um intervalo. Valores que não podem ser interpretados como números não correspondem. O avaliador atual interpreta o valor independentemente do tipo declarado; use Number em dados numéricos para clareza. Números JSON simples também são alternativas exatas, mas comparam a representação textual. [100] corresponde a "100", não a "100.0". Use numeric para igualdade matemática. Prefixos e sufixos comparam texto literal. Não há curingas, expressões regulares, filtros aninhados do corpo, atributos com arrays ou operadores que ignorem maiúsculas. Não presuma suporte a todos os operadores SNS.

Combinar presença e exclusão

Para aceitar um valor diferente de test, inclusive quando o atributo estiver ausente, inclua ambas as alternativas:

{
  "environment": [
    { "anything-but": "test" },
    { "exists": false }
  ]
}

Dois itens na lista não exigem prefixo e sufixo ao mesmo tempo: significam OR. Publique um atributo de roteamento separado com a classificação combinada quando precisar dessa condição.

Definir ou limpar uma política

Console
API
CLI
Go

Abra Subscriptions no tópico e selecione Subscribe. Cole um objeto JSON em Filter policy na criação. Deixe vazio para receber tudo. O formulário verifica sintaxe; a API valida operadores e limites.Abra Filter policy na assinatura existente para inspecionar; use a API para substituir ou limpar.

Defina filter_policy ao criar ou substitua com PATCH:

PATCH /v1/topics/{topic_id}/subscriptions/{subscription_id}
Content-Type: application/json

{
  "filter_policy": {
    "severity": ["critical", "error"]
  }
}

PATCH substitui a política inteira, sem mesclar nomes de atributos. Envie {"filter_policy": {}} para remover o filtro. Omitir o campo preserva a política.

Salve a solicitação JSON da aba API como request-1.json. Defina SUBSCRIPTION_ID, TOPIC_ID com os UUIDs dos recursos. Use sua conta e região configuradas.

basaltic notifications subscription update "$TOPIC_ID" "$SUBSCRIPTION_ID" --from-file request-1.json

Salve a solicitação JSON da aba API como request-1.json. Defina SUBSCRIPTION_ID, TOPIC_ID com os UUIDs dos recursos. Configure credenciais, conta e região pelas variáveis de ambiente do SDK.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	basaltic "github.com/basaltic-sh/sdk-go"
	"github.com/basaltic-sh/sdk-go/notifications"
)

func readJSON(path string, value any) error {
	data, err := os.ReadFile(path)
	if err != nil {
		return err
	}
	return json.Unmarshal(data, value)
}

func run() error {
	ctx := context.Background()
	cfg, err := basaltic.NewConfig(ctx)
	if err != nil {
		return err
	}
	client := notifications.New(cfg)
	var request1 notifications.UpdateSubscriptionRequest
	if err := readJSON("request-1.json", &request1); err != nil {
		return err
	}
	result1, err := client.UpdateSubscription(ctx, os.Getenv("TOPIC_ID"), os.Getenv("SUBSCRIPTION_ID"), &request1)
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", result1)
	return nil
}

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

Limites e validação

Item	Limite
Nomes de atributos por filtro	20
Alternativas por atributo	1–50
Valores em `anything-but`	1–50
Atributos por mensagem publicada	20
Nome do atributo publicado	1–256 bytes
Valor do atributo publicado	Até 1.024 bytes
Tipos de atributo publicado	`String` ou `Number`

Cada objeto deve ter exatamente um operador. Prefixos e sufixos não podem ser vazios. Listas numéricas precisam de pares completos operador/número. Alternativas vazias e operadores desconhecidos são inválidos. Políticas malformadas retornam HTTP 400 com NOTIFICATION_INVALID_FILTER_POLICY. Uma assinatura filtrada não tem registro de entrega nem tentativa com falha. Se houver menos entregas que o esperado, verifique confirmação, nomes e valores exatos e todas as condições. Mudanças afetam decisões de distribuição posteriores; não criam nem removem registros existentes retroativamente.

Primeiros passos

Produtos

Plataforma

Ajuda

Políticas de filtro

Um exemplo completo

Como combinar condições

Comparações disponíveis

Combinar presença e exclusão

Definir ou limpar uma política

Limites e validação

​Um exemplo completo

​Como combinar condições

​Comparações disponíveis

​Combinar presença e exclusão

​Definir ou limpar uma política

​Limites e validação

Um exemplo completo

Como combinar condições

Comparações disponíveis

Combinar presença e exclusão

Definir ou limpar uma política

Limites e validação