Create and configure a native OSS trigger to respond to events such as file uploads - Function Compute: Central de Documentação do Alibaba Cloud

Cenário de exemplo

Configure um gatilho do OSS e defina seu prefixo de objeto como source. Ao fazer upload de uma imagem para o diretório source no bucket do OSS especificado, o gatilho invoca a função automaticamente. A função redimensiona a imagem e a salva no diretório processed do mesmo bucket. Por exemplo, a função processa source/a.png e salva o resultado como processed/a.png.

Pré-requisitos

Function Compute
- Criar uma função acionada por eventos

Object Storage Service (OSS)
- Criar um bucket no console

Limitações

Um único bucket pode ter no máximo 10 gatilhos nativos do OSS.

Nota
Caso precise associar mais gatilhos do OSS a um bucket, crie gatilhos do OSS baseados no EventBridge. No entanto, não recomendamos associar mais de 10 gatilhos a um único bucket. Se precisar de mais, considere criar um novo bucket e configurar gatilhos para ele.
Gatilhos nativos do OSS e gatilhos do OSS baseados no EventBridge não suportam correspondência por caractere curinga ou expressão regular para prefixos e sufixos de objetos.
Um gatilho nativo do OSS suporta apenas um prefixo e um sufixo de objeto. Para configurar vários prefixos ou sufixos, utilize um gatilho do OSS baseado no EventBridge.

Etapa 1: Criar um gatilho do OSS

Acesse o console do Function Compute. No painel de navegação à esquerda, escolha Function Management > Functions.
Na barra de navegação superior, selecione uma região. Na página Functions, clique em na função desejada.

Na página de detalhes da função, selecione a aba Trigger e clique em Create Trigger. No painel Create Trigger, configure os parâmetros e clique em OK.

Parâmetro	Ações	Exemplo
Trigger Type	Selecione OSS.	OSS
Name	Insira um nome personalizado para o gatilho.	oss-trigger
Version or Alias	O valor padrão é LATEST. Para criar um gatilho para uma versão ou alias diferente, selecione-o primeiro na lista suspensa Version or Alias na página de detalhes da função. Para obter mais informações sobre versões e aliases, consulte Gerenciar versões e Gerenciar aliases.	LATEST
Bucket Name	Selecione o bucket do OSS criado.	testbucket
Object Prefix	Insira o prefixo dos nomes de objeto a serem correspondidos. Recomendamos especificar tanto um prefixo quanto um sufixo de objeto para evitar invocações recursivas do gatilho que podem gerar cobranças extras. Além disso, se gatilhos diferentes no mesmo bucket compartilharem o mesmo tipo de evento, seus prefixos e sufixos não devem ser idênticos. Para obter mais informações, consulte Regras de acionamento para gatilhos do OSS. Importante O prefixo do objeto não pode começar com uma barra (`/`). Caso contrário, o gatilho não será invocado.	source
Object Suffix	Insira o sufixo dos nomes de objeto a serem correspondidos. É altamente recomendável especificar tanto um prefixo quanto um sufixo para evitar invocações recursivas do gatilho que podem gerar cobranças extras. Além disso, se gatilhos diferentes no mesmo bucket compartilharem o mesmo tipo de evento, seus prefixos e sufixos não devem ser idênticos. Para obter mais informações, consulte Regras de acionamento para gatilhos do OSS.	png
Trigger Event	Selecione um ou mais eventos de gatilho. Para obter mais informações sobre os tipos de eventos para OSS, consulte Definições de eventos do OSS. Este exemplo utiliza oss:ObjectCreated:PutObject.	`oss:ObjectCreated:PutObject`, `oss:ObjectCreated:PostObject`, `oss:ObjectCreated:CompleteMultipartUpload`, `oss:ObjectCreated:PutSymlink`
Role Name	Selecione AliyunOSSEventNotificationRole. Nota Se esta for a primeira vez que você cria esse tipo de gatilho, clique em Authorize Now na caixa de diálogo exibida após clicar em OK.	AliyunOSSEventNotificationRole

Após a criação, o gatilho aparece na lista Trigger Name. Para modificar ou excluir o gatilho, consulte Gerenciar gatilhos.

Etapa 2: (Opcional) Configurar parâmetros de entrada da função

A fonte de eventos do OSS passa dados para sua função como um objeto event. Analise e processe esse objeto no seu código. Também é possível passar manualmente um event de amostra para a função, a fim de simular um gatilho e testar seu código.

Na aba Code da página de detalhes da função, clique em no ícone ao lado de Test Function e selecione Configure Test Parameters na lista suspensa.

No painel Configure Test Parameters, selecione a aba Create New Test Event ou Modify Existing Test Event. Insira um nome de evento e o conteúdo do evento e, em seguida, clique em OK.

Nota

Configure o conteúdo do evento com base nas informações fornecidas durante a criação do gatilho. Certifique-se de que o objeto especificado, source/a.png neste exemplo, exista no bucket. Caso contrário, a função não será invocada ou a invocação falhará.

O evento é um parâmetro de entrada para uma função do Function Compute. Quando um objeto é criado ou excluído no bucket do OSS especificado, o OSS envia os dados do evento para a função vinculada no formato JSON. O exemplo a seguir ilustra esse processo:

{
    "events": [
        {
            "eventName": "ObjectCreated:PutObject",
            "eventSource": "acs:oss",
            "eventTime": "2022-08-13T06:45:43.000Z",
            "eventVersion": "1.0",
            "oss": {
                "bucket": {
                    "arn": "acs:oss:cn-hangzhou:123456789:testbucket",
                    "name": "testbucket",
                    "ownerIdentity": "164901546557****"
                },
                "object": {
                    "deltaSize": 122539,
                    "eTag": "688A7BF4F233DC9C88A80BF985AB****",
                    "key": "source/a.png",
                    "objectMeta": {
                       "mimeType": "application/zip",
                       "userMeta": {
                          "x-oss-meta-last-modified":"20250213"
                       }
                    },
                    "size": 122539
                },
                "ossSchemaVersion": "1.0",
                "ruleId": "9adac8e253828f4f7c0466d941fa3db81161****"
            },
            "region": "cn-hangzhou",
            "requestParameters": {
                "sourceIPAddress": "140.205.XX.XX"
            },
            "responseElements": {
                "requestId": "58F9FF2D3DF792092E12044C"
            },
            "userIdentity": {
                "principalId": "164901546557****"
            }
        }
    ]
}

A tabela a seguir descreve os parâmetros em um objeto de evento.

Parâmetro	Tipo	Valor	Descrição
eventName	String	ObjectCreated:PutObject	O tipo de evento.
eventSource	String	acs:oss	A fonte do evento. O valor é fixo como `acs:oss`.
eventTime	String	2022-08-13T06:45:43.000Z	O horário em que o evento ocorreu, no formato ISO 8601.
eventVersion	String	1.0	A versão do protocolo de evento.
oss	Map		Contém os detalhes do evento do OSS.
bucket	Map		O valor do parâmetro bucket.
name	String	testbucket	O nome do bucket.
arn	String	acs:oss:cn-hangzhou:123456789:testbucket	O identificador exclusivo do bucket.
ownerIdentity	String	164901546557****	O ID do usuário que criou o bucket.
object	Map		O conteúdo do parâmetro object.
size	Int	122539	O tamanho do object. Unidade: Byte.
deltaSize	Int	122539	A alteração no tamanho do object. Unidade: Byte. Se um novo objeto for adicionado, este valor corresponde ao tamanho do objeto. Se um objeto existente for sobrescrito por outro com o mesmo nome, este valor representa a diferença de tamanho entre os objetos novo e antigo.
eTag	String	688A7BF4F233DC9C88A80BF985AB****	O ETag do objeto.
key	String	source/a.png	O caminho completo do objeto.
objectMeta	Map		Conteúdo do parâmetro objectMeta.
mimeType	String	application/zip	O tipo de arquivo do objeto. Para obter mais informações, consulte mimeType.
userMeta	Map		Os metadados do usuário que identificam a finalidade ou os atributos do objeto.
x-oss-meta-last-modified	String	20250213	Os metadados do usuário consistem em pares chave-valor. A chave de metadados deve começar com `x-oss-meta-`. Por exemplo, o par `"x-oss-meta-last-modified":"20250213"` indica que o arquivo local foi modificado pela última vez em 13 de fevereiro de 2025. Para obter mais informações, consulte Metadados do usuário.
ossSchemaVersion	String	1.0	A versão do esquema do OSS.
ruleId	String	9adac8e253828f4f7c0466d941fa3db81161****	O ID da regra de gatilho correspondente ao evento.
region	String	cn-hangzhou	A região do bucket.
requestParameters	Map		Os parâmetros da solicitação.
sourceIPAddress	String	140.205.XX.XX	O endereço IP de origem da solicitação.
responseElements	Map		Os elementos da resposta.
requestId	String	58F9FF2D3DF792092E12044C	O ID da solicitação.
userIdentity	Map		A identidade do usuário que fez a solicitação.
principalId	String	164901546557****	O ID da conta Alibaba Cloud que iniciou a solicitação.

Etapa 3: Escrever e testar o código da função

Após criar o gatilho do OSS, escreva e teste o código da função para verificar se ele funciona corretamente. Em um cenário real, o gatilho invoca a função automaticamente quando o evento especificado do OSS ocorre.

Aviso

É essencial evitar invocações recursivas no seu código. Um cenário comum de recursão ocorre quando uma função é acionada pelo upload de um objeto em um bucket do OSS. Após a execução, a função gera um ou mais novos objetos e os grava de volta no mesmo bucket. Essa operação de gravação aciona a função novamente, criando um loop infinito. Para obter mais informações, consulte Regras de acionamento para gatilhos do OSS.

Na aba Code da página de detalhes da função, insira seu código no editor e clique em Deploy.

O código de exemplo a seguir destina-se a runtimes que suportam edição online.

Nota

Recomendamos o uso de um endpoint interno do OSS para ler e gravar dados em buckets do OSS dentro da sua função. O uso de um endpoint público gera cobranças de transferência de dados pela internet. Para obter mais informações sobre endpoints internos, consulte Regiões e endpoints.

"use strict";
/*
This sample code shows you how to perform the following operations:
* 1. Parse OSS event information from the event.
* 2. Initialize the OSS client based on the parsed information.
* 3. Resize the source image and save it to a destination directory in the same bucket.
*/

const OSS = require("ali-oss");

exports.handler = async function(event, context, callback) {
    console.log("The content in context entity is: \n");
    console.dir(context);

    const {accessKeyId, accessKeySecret, securityToken} = context.credentials;

    const events = JSON.parse(event.toString()).events;
    console.log("The content in event entity is: \n");
    console.dir(events);

    let objectName = events[0].oss.object.key;
    let region = events[0].region;
    let bucketName = events[0].oss.bucket.name;

    // Connect to the target OSS bucket.
    const client = new OSS({
        region: region,
        accessKeyId: accessKeyId,
        accessKeySecret: accessKeySecret,
        stsToken: securityToken,
        bucket: bucketName,
        endpoint: "https://oss-" + region + "-internal.aliyuncs.com"
    });

    console.log("The client entity is: \n");
    console.dir(events);

    const targetImage = objectName.replace("source/", "processed/")
    // Resize the image to a fixed width and height of 128 px.
    const processStr = "image/resize,m_fixed,w_128,h_128"
    // Resize the source image and save the processed image to the destination path.
    const result = await client.processObjectSave(
        objectName,
        targetImage,
        processStr,
        bucketName
    );
    console.log(result.res.status);

    callback(null, "done");
}

"""
This sample code shows you how to perform the following operations:
* Get OSS processing-related information from the event.
* Initialize the OSS client with the target bucket.
* Resize the source image and save it to a destination directory.
"""

# -*- coding: utf-8 -*-
import oss2, json
import base64

def handler(event, context):
    # Obtain key information from context.credentials.
    print("The content in context entity is: \n")
    print(context)
    creds = context.credentials

    # Configure authentication for the OSS SDK.
    auth = oss2.StsAuth(
        creds.access_key_id,
        creds.access_key_secret,
        creds.security_token)

    print("The content in event entity is: \n")
    print(event)
    # Load event content.
    oss_raw_data = json.loads(event)
    # Get OSS event parameters passed by the OSS trigger.
    oss_info_map = oss_raw_data['events'][0]['oss']
    # Get the OSS bucket name.
    bucket_name = oss_info_map['bucket']['name']
    # Set the OSS endpoint.
    endpoint = 'oss-' + oss_raw_data['events'][0]['region'] + '-internal.aliyuncs.com'
    # Initialize the OSS client.
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    object_name = oss_info_map['object']['key']

    # Download the original image from the OSS bucket.
    remote_stream = bucket.get_object(object_name)
    if not remote_stream:
        print(f'{object_name} does not exist in bucket {bucket_name}')
        return
    # Processed images are saved to the processed/ directory.
    processed_path = object_name.replace('source/', 'processed/')

    # Resize the image to a fixed width and height of 128 px.
    style = 'image/resize,m_fixed,w_128,h_128'
    # Specify the name of the processed image. If the image is not in the root directory of the bucket, you must specify the full path of the image. Example: exampledir/example.jpg.
    process = "{0}|sys/saveas,o_{1},b_{2}".format(style,
        oss2.compat.to_string(base64.urlsafe_b64encode(oss2.compat.to_bytes(processed_path))),
        oss2.compat.to_string(base64.urlsafe_b64encode(oss2.compat.to_bytes(bucket_name))))
    result = bucket.process_object(object_name, process)
    print(result)

/*
*This sample code shows you how to perform the following operations:
* 1. Parse the endpoint, bucket, and object from the event.
* 2. Initialize the OSS client based on the parsed information.
* 3. Resize the source image and save the processed image to a destination directory in the same bucket.
*/
<?php

use RingCentral\Psr7\Response;
use OSS\OssClient;
use OSS\Core\OssException;

function base64url_encode($data)
{
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

function handler($event, $context) {
  $event           = json_decode($event, $assoc = true);
  /*
    An AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M.
    Do not hard-code the AccessKey ID and AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked, which compromises the security of all resources in your account.
    This example shows how to obtain the AccessKey pair from the context.
  */
  $accessKeyId     = $context["credentials"]["accessKeyId"];
  $accessKeySecret = $context["credentials"]["accessKeySecret"];
  $securityToken   = $context["credentials"]["securityToken"];
  $evt        = $event['events']{0};
  $bucketName = $evt['oss']['bucket']['name'];
  $endpoint   = 'oss-' . $evt['region'] . '-internal.aliyuncs.com';
  $objectName = $evt['oss']['object']['key'];
  $targetObject = str_replace("source/", "processed/", $objectName);

    try {
        // Connect to OSS.
        $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false, $securityToken);
        // Resize the image to a fixed width and height of 128 px.
        $style = "image/resize,m_fixed,w_128,h_128";
        $process = $style.
           '|sys/saveas'.
           ',o_'.base64url_encode($targetObject).
           ',b_'.base64url_encode($bucketName);
        // Resize the image and save it to the destination object.
        $result = $ossClient->processObject($bucketName, $objectName, $process);
        // Print the processing result.
        print($result);
    } catch (OssException $e) {
        print_r(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
    }

    print(__FUNCTION__ . ": OK" . "\n");

    return $targetObject;
}

Teste a função.

Método 1: Se você configurou o parâmetro de entrada event para simular uma fonte de eventos, clique em Test Function.

Método 2: Na página Configuration > Trigger, clique em no Bucket Name para acessar o bucket correspondente. Faça upload de uma imagem que corresponda ao prefixo e sufixo de objeto especificados. Após a execução da função, visualize os logs de execução na aba Logs e verifique o resultado na pasta de destino do bucket.

Perguntas frequentes

Referências

Para conhecer os tipos de eventos do OSS configuráveis, consulte Definições de eventos do OSS.
Para modificar ou excluir um gatilho, consulte Atualizar um gatilho.
Caso precise associar mais de 10 gatilhos do OSS a um bucket, consulte Configurar um gatilho do OSS baseado no EventBridge.
Problemas relacionados a gatilhos:
- Para verificar qual evento invocou sua função, registre o tipo de evento no seu código. Para obter mais informações, consulte Gerenciamento de logs.
- Para chamar uma função a partir de outra, faça uma chamada direta de API ou use o CloudFlow para orquestrá-las. Se você invocar de forma assíncrona uma função que executa uma tarefa de longa duração, configure um destino para lidar com o resultado da invocação. Para obter mais informações, consulte As funções podem invocar umas às outras? e Configurar um destino para uma invocação assíncrona.