Função do Extrator do Arquivo de Armazenamento de Objetos

Descubra como usar a função pré-criada do Object Storage File Extractor no OCI Functions para ler um arquivo zip de um bucket do OCI Object Storage e extraí-lo para o bucket de destino especificado.

Cenário de Uso Comum

As maneiras comuns de usar a função File Extractor do Object Storage incluem:

Coloque um zip no armazenamento de objetos e use o Data Integration para descompactar o arquivo e armazenar o resultado no armazenamento de objetos.
Coloque um zip no armazenamento de objetos e chame diretamente a função para descompactar os arquivos e armazenar o resultado no armazenamento de objetos.

Os serviços relacionados à função File Extractor do Object Storage incluem:

Escopo

As considerações de escopo para esta função incluem:

A função pré-criada funciona melhor se o timeout padrão for definido como 300 segundos.

Pré-requisitos e Recomendações

Veja a seguir as melhores práticas ao usar esta função predefinida:

Defina o timeout da função pré-criada como 300 segundos.
A VCN vinculada ao aplicativo facilita o acesso a outros serviços do OCI usando um Gateway de Serviço, Gateway de Internet ou gateway NAT.
Defina o tamanho da memória padrão como a memória máxima permitida para uma função.

Configurando a Função do Extrator do Arquivo de Armazenamento de Objetos

Para configurar uma função Extrator de Arquivos do Object Storage, execute as seguintes etapas:

Na página Funções Pré-integradas, selecione Extrator de Arquivos do Serviço Object Storage e, em seguida, selecione Criar função.
Configure o Nome, o Compartimento e o Aplicativo da seguinte maneira:
- Nome: Um nome de sua escolha para a nova função. O nome deve começar com letra ou sublinhado, seguido de letras, números, traços ou sublinhados. O tamanho pode ser de 1 a 255 caracteres. Evite digitar informações confidenciais.
  Para criar a função em outro compartimento, selecione Alterar Compartimento.
- Aplicativo: selecione o aplicativo no qual você deseja criar a função.
  Se ainda não existir um aplicativo adequado no compartimento atual, selecione Criar novo aplicativo e especifique os seguintes detalhes:
  - Nome: Um nome para o novo aplicativo. Evite digitar informações confidenciais.
  - VCN: A VCN (rede virtual na nuvem) na qual executar funções no aplicativo. Opcionalmente, selecione Alterar Compartimento para selecionar uma VCN de outro compartimento.
  - Sub-redes: A sub-rede (ou sub-redes, até no máximo três) na qual executar funções. Opcionalmente, selecione Alterar Compartimento para selecionar uma sub-rede de outro compartimento.
  - Forma: A arquitetura do processador das instâncias de computação nas quais implantar e executar funções no aplicativo. Todas as funções no aplicativo são implantadas e executadas em instâncias de computação com a mesma arquitetura. A imagem da função deve conter as dependências necessárias para a arquitetura selecionada.
  - Opções de tag: Se você tiver permissões para criar um recurso, também terá permissões para aplicar tags de formato livre a esse recurso. Para aplicar uma tag definida, você deverá ter permissões para usar o namespace da tag. Para obter mais informações sobre tags, consulte Tags de Recursos. Se você não tiver certeza se deseja aplicar tags, ignore esta opção ou pergunte a um administrador. Você pode aplicar tags posteriormente.
Configure a política do IAM para funções pré-criadas.

Por padrão, o OCI Functions cria um grupo dinâmico e uma política do IAM com as instruções de política necessárias para executar a função pré-criada. Não faça alterações para aceitar o comportamento padrão.

Se você não quiser que o OCI Functions crie automaticamente o grupo dinâmico e a política, selecione Não criar um grupo dinâmico e uma política de IAM.

Importante

Se você selecionar a opção Não criar um grupo dinâmico e uma política de IAM, deverá definir você mesmo o grupo dinâmico e a política de IAM. Para obter mais informações, consulte Permissões.
Configure a memória da função e os valores de timeout da seguinte forma:
- Memória: A quantidade máxima de memória que a função pode usar durante a execução, em megabytes. Essa é a memória disponível para a imagem da função. (Padrão: 256 MB)
- Timeout: A quantidade máxima de tempo no qual a função pode ser executada, em segundos. Se a função não for concluída no tempo especificado, o sistema cancelará a função. (Padrão: 300)
(Opcional) Configure a Simultaneidade provisionada para minimizar atrasos iniciais ao chamar a função especificando um número mínimo de chamadas de função simultâneas para as quais você deseja que a infraestrutura de execução esteja constantemente disponível. (Padrão: não selecionado)

Se selecionado, especifique o número de unidades de simultaneidade provisionadas atribuídas a esta função. Padrão: 10.

Para obter mais informações sobre simultaneidade provisionada, consulte Reduzindo a latência inicial usando simultaneidade provisionada.
Defina os parâmetros de configuração da função conforme descrito em Parâmetros de Configuração.
Opcionalmente, informe qualquer tag na seção Opções de tag. Se você tiver permissões para criar um recurso, também terá permissões para aplicar tags de formato livre a esse recurso. Para aplicar uma tag definida, você deverá ter permissões para usar o namespace da tag. Para obter mais informações sobre tags, consulte Tags de Recursos. Se você não tiver certeza se deseja aplicar tags, ignore esta opção ou pergunte a um administrador. Você pode aplicar tags posteriormente.
Selecione Criar.

A caixa de diálogo de implantação exibe as tarefas para implantar a função (consulte Finalizando a Implantação de Função Pré-Criada).

Opções de Configuração

Parâmetros de configuração


Nome	Descrição	Obrigatórias
`PBF_LOG_LEVEL`	No nível de log, as opções são `DEBUG`, `INFO`, `WARN` e `ERROR`. O padrão é INFO.	No

Permissões

A execução de uma função requer determinadas políticas do serviço IAM. Se você tiver selecionado a opção Não criar um grupo dinâmico e uma política do serviço IAM ao criar a função, defina você mesmo o grupo dinâmico e a política do serviço IAM.

Para definir as políticas adequadas, execute as seguintes etapas:

Crie um grupo dinâmico com a regra:

ALL {resource.id = '<function_ocid>', resource.compartment.id = '<compartment_ocid>'}

Configure uma política do IAM usando o grupo dinâmico:

Allow dynamic-group <dynamic-group-name> to read objectstorage-namespaces in compartment <compartment-name>
Allow dynamic-group <dynamic-group-name> to manage objects in compartment <compartment-name>
Allow dynamic-group <dynamic-group-name> to manage buckets in compartment <compartment-name>
Allow dynamic-group <dynamic group name> to read compartments in compartment <compartment-name>

Observação

Substitua <function-ocid> pelo OCID da função que você criou nas etapas anteriores.

Observação

Substitua <dynamic-group-name> pelo nome do grupo dinâmico que você criou usando o OCID da função.

Observação

Substitua <compartment_ocid> pelo OCID do compartimento que contém a função.

Chamando Esta Função

Você pode chamar a função das seguintes maneiras:

Chame a função diretamente conforme documentado em Chamando Funções criando um corpo de solicitação, conforme mostrado no exemplo JSON a seguir.
Chame a função por meio do Data Integration. Aproveite a tarefa da API REST para configurar o ponto final de chamada com o corpo da solicitação, juntamente com parâmetros para acionar a função. O corpo REST adere aos seguintes valores JSON.

Valores JSON da Solicitação HTTP


Nome	Descrição	Obrigatórias
COMPARTMENT_ID	OCID do Compartimento do bucket de origem.	Sim
REGIÃO	A região na qual os buckets existem. O padrão é a região na qual a função é criada.	N.o
SOURCE_BUCKET	Nome do bucket de origem que contém o arquivo zip.	Sim
ZIP_FILE_NAME	Nome do arquivo zip.	Sim
TARGET_BUCKET	Nome do bucket de destino. Se o bucket de destino com o nome fornecido não existir, o bucket será criado pela função pré-criada.	Sim
ALLOW_OVERWRITE	Aceita `true` ou `false`. Se o atributo não for fornecido, o valor padrão será `false`. O valor `true` significa que a descompactação do arquivo substitui os arquivos com o mesmo nome no destino. Um valor `false` significa que a descompactação cria uma cópia com controle de versão do arquivo ou da pasta pai. Exemplo de conteúdo do arquivo zip: `folder_1/text_file_1.txt folder_1/sub_folder_1/text_file_2.txt text_file_3.txt` Se o destino já tiver `folder_1` e `text_file_3.txt` na raiz, o bucket de destino será agora: `folder_1/text_file_1.txt # already existing folder folder_1/text_file_4.txt # already existing folder folder_1 (1)/text_file_1.txt folder_1 (1)/sub_folder_1/text_file_2.txt text_file_3.txt # already existing file text_file_3 (1).txt`	No

Corpo da Solicitação de Amostra

{
    "COMPARTMENT_ID": "ocid1.compartment.oc1...",
    "REGION": "us-ashburn-1",
    "SOURCE_BUCKET": "origin-storage",
    "ZIP_FILE_NAME": "object_extractor_example.zip",
    "TARGET_BUCKET": "target-storage ",
    "ALLOW_OVERWRITE": "false"
}

Corpo da Resposta

Timestamp: Usando UTC para evitar problemas de fuso horário.
Código: A função retornará um código 200 se a tarefa for concluída com sucesso.
Status: A função retornará "Sucesso" como o status se a tarefa for concluída com sucesso.
dados: Um corpo de mensagem JSON que inclui informações de resposta específicas para a tarefa. As informações adicionais fornecem uma mensagem de confirmação da operação de descompactação bem-sucedida.

Exemplo

O exemplo a seguir mostra os dados de retorno JSON:

{
    "startTime": "2023-02-22T05:55:06.544Z",
    "endTime": "2023-02-22T05:55:17.730Z",
    "runTime": "PT11.186S",
    "code": 200,
    "status": "Success",
    "data": {
        "additionalInformation": {
            "Message": "Unzip task is successfully done"
        }
    }
}

Diagnóstico e Solução de Problemas

Códigos de status comuns do OCI Functions

A tabela a seguir resume os erros comuns do OCI Functions que você pode encontrar ao trabalhar com funções predefinidas:


Código do Erro	Mensagem de Erro	Ação
200	Bem-sucedido	Nenhuma
404	NotAuthorizedOrNotFound	Verifique se as políticas necessárias estão configuradas (consulte A execução dos comandos da CLI do Fn Project retorna um erro 404).
444	Timeout	A conexão entre o cliente e o OCI Functions foi interrompida durante a execução da função (consulte Chamar uma função faz com que o cliente reporte um timeout e um erro 444 é mostrado nos logs da função). Uma nova tentativa pode resolver o problema. Observe que a maioria dos clientes tem um tempo limite interno de 60 segundos. Mesmo quando o timeout da função pré-criada é definido como 300 segundos, o seguinte pode ser necessário: Ao usar a CLI do OCI: Use --read-timeout 300 Ao usar o OCI SDK: Defina o timeout de leitura como 300 ao criar o cliente Ao usar DBMS_CLOUD.SEND_REQUEST: Use UTL_HTTP.set_transfer_timeout(300); Para obter mais informações, consulte Chamando Funções.
502 504	(vários)	A maioria dos problemas retorna um código de status 502 (consulte Chamar uma função retorna uma mensagem de falha da Função e um erro 502). Um erro 502 com a mensagem "erro recebendo resposta da função" pode ser resolvido aumentando a alocação de memória. Um 502 pode ocorrer ocasionalmente quando a função está em algum estado transitório. Uma nova tentativa pode resolver o problema.

Para identificar ainda mais a causa, ative os recursos de log para a função pré-criada (consulte Armazenando e Exibindo Logs de Função). Para obter informações detalhadas sobre como diagnosticar e solucionar problemas de uma função, consulte Diagnosticando e Solucionando Problemas do OCI Functions.

Códigos de status da função pré-criada do Extrator de Arquivos do Serviço Object Storage

A tabela a seguir resume os erros que você pode encontrar ao trabalhar com essa função predefinida:


Código do Erro	Mensagem de Erro	Ação
400	Valor de configuração obrigatório não encontrado	A mensagem de erro indica o nome do campo obrigatório. Verifique se o campo correto é fornecido no corpo da solicitação.
400	Nome de arquivo zip inválido	Verifique se o nome do arquivo fornecido para o campo `ZIP_FILE_NAME` tem uma extensão `.zip`.
409	O bucket de destino já contém um arquivo compactado com o mesmo nome	Se `ALLOW_OVERWRITE` estiver definido como `false`, verifique se o bucket de destino ainda não tem um arquivo zip com o mesmo nome.

Para identificar ainda mais a causa, ative os recursos de log para a função pré-criada (consulte Armazenando e Exibindo Logs de Função).

Dicas de Análise de Log

Todas as funções pré-criadas fornecem uma opção para especificar o nível de log como um parâmetro de configuração. Você pode definir o nível de log como DEBUG para obter mais informações.

Como um aplicativo tem várias funções, as entradas de log de função pré-criadas são identificadas pelo prefixo "PBF | <PBF NAME> ".

Por exemplo, uma entrada de log para a função pré-criada do Gerador de Job do Workflow de Mídia é semelhante à seguinte:

"PBF | Media Workflow Job Spawner | INFO | 2023-02-07T18:06:50.809Z | Fetching details from Events JSON"

Documentação do Oracle Cloud Infrastructure