Configurar notificações de eventos usando filtragem de nomes de chave de objeto - Amazon Simple Storage Service
Exemplos de configurações válidas de notificação com filtragem de nome de chave de objetoExemplos de configurações de notificação com sobreposição inválida de prefixo e sufixo

Configurar notificações de eventos usando filtragem de nomes de chave de objeto

Ao configurar uma notificação de evento do Amazon S3, você deve especificar quais tipos de evento suportados do Amazon S3 fazem com que o Amazon S3 envie a notificação. Se um tipo de evento que você não especificou ocorrer no bucket do S3, o Amazon S3 não enviará a notificação.

Você pode configurar as notificações para serem filtradas pelo prefixo e pelo sufixo do nome da chave de objetos. Por exemplo, é possível definir uma configuração para que uma notificação seja enviada para você apenas quando arquivos de imagem com uma extensão de nome de arquivo ".jpg" forem adicionados a um bucket. Ou ter uma configuração que entregue uma notificação a um tópico do Amazon SNS quando um objeto com o prefixo "images/" for adicionado ao bucket, e fazer com que notificações para objetos com um prefixo "logs/" no mesmo bucket sejam entregues a uma função do AWS Lambda.

nota

Um caractere curinga (“*”) não pode ser usado em filtros como um prefixo ou sufixo. Se seu prefixo ou sufixo contiver um espaço, você deverá substituí-lo pelo caractere “+”. Se você usar qualquer outro caractere especial no valor do prefixo ou sufixo, deverá inseri-los no formato codificado em URL (codificado em porcentagem). Para obter uma lista completa de caracteres especiais que devem ser convertidos em formato codificado em URL quando usados em um prefixo ou sufixo para notificações de eventos, consulte Caracteres seguros.

É possível definir configurações de notificação que usem filtro de nomes de chaves de objetos no console do Amazon S3. Você pode fazer isso usando as APIs do Amazon S3 por meio dos AWS SDKs ou das APIs REST diretamente. Para obter informações sobre como usar a interface do usuário do console para definir uma configuração de notificação em um bucket, consulte Habilitar e configurar notificações de eventos usando o console do Amazon S3.

O Amazon S3 armazena a configuração de notificação como XML no sub-recurso notificação associado a um bucket, conforme descrito em Usar o Amazon SQS, o Amazon SNS e o Lambda. Use a estrutura XML do Filter para definir regras para que as notificações sejam filtradas pelo prefixo ou pelo sufixo do nome da chave de um objeto. Para obter informações sobre a estrutura XML Filter, consulte Notificação de PUT Bucket na Referência da API do Amazon Simple Storage Service.

Configurações de notificação que usam o Filter não podem definir regras de filtragem com prefixos sobrepostos, sufixos sobrepostos ou prefixos e sufixos sobrepostos. As seções a seguir têm exemplos de configurações de notificação válidas com filtragem de nome de chave de objeto. Elas também contêm exemplos de configurações de notificação que não são válidas devido à sobreposição de prefixo e sufixo.

Exemplos de configurações válidas de notificação com filtragem de nome de chave de objeto

A configuração de notificação a seguir contém uma configuração de fila que identifica uma fila do Amazon SQS para a qual o Amazon S3 publica eventos do tipo s3:ObjectCreated:Put. Os eventos são publicados sempre que um objeto que tenha um prefixo images/ e um sufixo jpg é PUT em um bucket. 

<NotificationConfiguration>
  <QueueConfiguration>
      <Id>1</Id>
      <Filter>
          <S3Key>
              <FilterRule>
                  <Name>prefix</Name>
                  <Value>images/</Value>
              </FilterRule>
              <FilterRule>
                  <Name>suffix</Name>
                  <Value>jpg</Value>
              </FilterRule>
          </S3Key>
     </Filter>
     <Queue>arn:aws:sqs:us-west-2:444455556666:s3notificationqueue</Queue>
     <Event>s3:ObjectCreated:Put</Event>
  </QueueConfiguration>
</NotificationConfiguration>

A configuração de notificação a seguir tem vários prefixos não sobrepostos. A configuração define que as notificações para solicitações PUT na pasta images/ vão para a fila A, enquanto as notificações para solicitações PUT na pasta logs/ vão para a fila B.

<NotificationConfiguration>
  <QueueConfiguration>
     <Id>1</Id>
     <Filter>
            <S3Key>
                <FilterRule>
                    <Name>prefix</Name>
                    <Value>images/</Value>
                </FilterRule>
            </S3Key>
     </Filter>
     <Queue>arn:aws:sqs:us-west-2:444455556666:sqs-queue-A</Queue>
     <Event>s3:ObjectCreated:Put</Event>
  </QueueConfiguration>
  <QueueConfiguration>
     <Id>2</Id>
     <Filter>
            <S3Key>
                <FilterRule>
                    <Name>prefix</Name>
                    <Value>logs/</Value>
                </FilterRule>
            </S3Key>
     </Filter>
     <Queue>arn:aws:sqs:us-west-2:444455556666:sqs-queue-B</Queue>
     <Event>s3:ObjectCreated:Put</Event>
  </QueueConfiguration>
</NotificationConfiguration>

A configuração de notificação a seguir tem vários sufixos não sobrepostos. A configuração define que todas as imagens .jpg recém-adicionadas ao bucket sejam processadas por cloud-function-A do Lambda e que todas as imagens .png recém-adicionadas sejam processadas por cloud-function-B. Os sufixos .png e .jpg não se sobrepõem, apesar de terminarem com a mesma letra. Dois sufixos são considerados sobrepostos se determinada string puder terminar com ambos os sufixos. Uma string não pode terminar com .png e com .jpg, então os sufixos na configuração de exemplo não são sufixos sobrepostos. 

<NotificationConfiguration>
  <CloudFunctionConfiguration>
     <Id>1</Id>
     <Filter>
            <S3Key>
                <FilterRule>
                    <Name>suffix</Name>
                    <Value>.jpg</Value>
                </FilterRule>
            </S3Key>
     </Filter>
     <CloudFunction>arn:aws:lambda:us-west-2:444455556666:cloud-function-A</CloudFunction>
     <Event>s3:ObjectCreated:Put</Event>
  </CloudFunctionConfiguration>
  <CloudFunctionConfiguration>
     <Id>2</Id>
     <Filter>
            <S3Key>
                <FilterRule>
                    <Name>suffix</Name>
                    <Value>.png</Value>
                </FilterRule>
            </S3Key>
     </Filter>
     <CloudFunction>arn:aws:lambda:us-west-2:444455556666:cloud-function-B</CloudFunction>
     <Event>s3:ObjectCreated:Put</Event>
  </CloudFunctionConfiguration>
</NotificationConfiguration>

As configurações de notificação que usam o Filter não podem definir regras de filtro com prefixos sobrepostos para os mesmos tipos de evento. Eles só podem fazer isso se os prefixos sobrepostos forem usados com sufixos que não são sobrepostos. A configuração de exemplo a seguir mostra como objetos criados com um prefixo comum, mas com sufixos não sobrepostos, podem ser entregues a destinos diferentes.

<NotificationConfiguration>
  <CloudFunctionConfiguration>
     <Id>1</Id>
     <Filter>
            <S3Key>
                <FilterRule>
                    <Name>prefix</Name>
                    <Value>images</Value>
                </FilterRule>
                <FilterRule>
                    <Name>suffix</Name>
                    <Value>.jpg</Value>
                </FilterRule>
            </S3Key>
     </Filter>
     <CloudFunction>arn:aws:lambda:us-west-2:444455556666:cloud-function-A</CloudFunction>
     <Event>s3:ObjectCreated:Put</Event>
  </CloudFunctionConfiguration>
  <CloudFunctionConfiguration>
     <Id>2</Id>
     <Filter>
            <S3Key>
                <FilterRule>
                    <Name>prefix</Name>
                    <Value>images</Value>
                </FilterRule>
                <FilterRule>
                    <Name>suffix</Name>
                    <Value>.png</Value>
                </FilterRule>
            </S3Key>
     </Filter>
     <CloudFunction>arn:aws:lambda:us-west-2:444455556666:cloud-function-B</CloudFunction>
     <Event>s3:ObjectCreated:Put</Event>
  </CloudFunctionConfiguration>
</NotificationConfiguration>

Exemplos de configurações de notificação com sobreposição inválida de prefixo e sufixo

Na maioria das vezes, as configurações de notificação que usam Filter não podem definir regras de filtro com prefixos sobrepostos, sufixos sobrepostos ou combinações sobrepostas de prefixos e sufixos para os mesmos tipos de evento. Você pode ter prefixos sobrepostos, desde que os sufixos não se sobreponham. Para ver um exemplo, consulte Configurar notificações de eventos usando filtragem de nomes de chave de objeto.

Você pode usar filtros de nomes de chave de objetos sobrepostos com diferentes tipos de evento. Por exemplo, você poderia criar uma configuração de notificação que usasse o prefixo image/ para o tipo de evento ObjectCreated:Put e o prefixo image/ para o tipo de evento ObjectRemoved:*.

Você receberá um erro se tentar salvar uma configuração de notificação que tenha filtros de nomes sobrepostos inválidos para os mesmos tipos de evento ao usar o console ou a API do Amazon S3. Esta seção mostra exemplos de configurações de notificação que não são válidas devido aos filtros de nomes sobrepostos.

Presume-se que qualquer regra de configuração de notificação tenha um prefixo e um sufixo padrão que correspondam a qualquer outro prefixo e um sufixo, respectivamente. A configuração de notificação a seguir não é válida porque tem prefixos sobrepostos. Especificamente, o prefixo raiz sobrepõe qualquer outro prefixo. O mesmo se aplica se você usar um sufixo em vez de um prefixo neste exemplo. O sufixo raiz sobrepõe qualquer outro sufixo.

<NotificationConfiguration>
     <TopicConfiguration>
         <Topic>arn:aws:sns:us-west-2:444455556666:sns-notification-one</Topic>
         <Event>s3:ObjectCreated:*</Event>
    </TopicConfiguration>
    <TopicConfiguration>
         <Topic>arn:aws:sns:us-west-2:444455556666:sns-notification-two</Topic>
         <Event>s3:ObjectCreated:*</Event>
         <Filter>
             <S3Key>
                 <FilterRule>
                     <Name>prefix</Name>
                     <Value>images</Value>
                 </FilterRule>
            </S3Key>
        </Filter>
    </TopicConfiguration>             
</NotificationConfiguration>

A configuração de notificação a seguir não é válida porque tem sufixos sobrepostos. Dois sufixos são considerados sobrepostos se determinada string puder terminar com ambos os sufixos. Uma string pode terminar com jpg e pg. Portanto, os sufixos se sobrepõem. O mesmo vale para prefixos. Dois prefixos são considerados sobrepostos se determinada string puder começar com ambos os prefixos.

 <NotificationConfiguration>
     <TopicConfiguration>
         <Topic>arn:aws:sns:us-west-2:444455556666:sns-topic-one</Topic>
         <Event>s3:ObjectCreated:*</Event>
         <Filter>
             <S3Key>
                 <FilterRule>
                     <Name>suffix</Name>
                     <Value>jpg</Value>
                 </FilterRule>
            </S3Key>
        </Filter>
    </TopicConfiguration>
    <TopicConfiguration>
         <Topic>arn:aws:sns:us-west-2:444455556666:sns-topic-two</Topic>
         <Event>s3:ObjectCreated:Put</Event>
         <Filter>
             <S3Key>
                 <FilterRule>
                     <Name>suffix</Name>
                     <Value>pg</Value>
                 </FilterRule>
            </S3Key>
        </Filter>
    </TopicConfiguration>
</NotificationConfiguration

A configuração de notificação a seguir não é válida porque tem prefixos e sufixos sobrepostos. 

<NotificationConfiguration>
     <TopicConfiguration>
         <Topic>arn:aws:sns:us-west-2:444455556666:sns-topic-one</Topic>
         <Event>s3:ObjectCreated:*</Event>
         <Filter>
             <S3Key>
                 <FilterRule>
                     <Name>prefix</Name>
                     <Value>images</Value>
                 </FilterRule>
                 <FilterRule>
                     <Name>suffix</Name>
                     <Value>jpg</Value>
                 </FilterRule>
            </S3Key>
        </Filter>
    </TopicConfiguration>
    <TopicConfiguration>
         <Topic>arn:aws:sns:us-west-2:444455556666:sns-topic-two</Topic>
         <Event>s3:ObjectCreated:Put</Event>
         <Filter>
             <S3Key>
                 <FilterRule>
                     <Name>suffix</Name>
                     <Value>jpg</Value>
                 </FilterRule>
            </S3Key>
        </Filter>
    </TopicConfiguration>
</NotificationConfiguration>