Documentação do Oracle Cloud Infrastructure

Função do Gerador de Documentos

Descubra como usar a função predefinida do Gerador de Documentos no OCI Functions para gerar documentos com base em modelos do Office e dados JSON.

Cenário de Uso Comum

As formas comuns de usar a função Gerador de Documentos incluem:

  • Coloque um Modelo do Office e dados JSON no armazenamento de objetos e chame diretamente a função para gerar documentos PDF e armazenar os resultados no armazenamento de objetos.

Os serviços relacionados à função Gerador de Documentos incluem:

Pré-requisitos e Recomendações

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

  • 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 de memória padrão como 512 MB para a maioria das tarefas. Usar conjuntos de dados maiores, empacotar fontes ou usar processamento em lote pode exigir mais memória.
  • Para processamento em lote, defina o tempo limite da função predefinida como 300 segundos.

Configurando a Função do Gerador de Documentos

Para configurar uma função Gerador de Documentos, execute as seguintes etapas:

  1. Na página Funções Pré-Criadas, selecione Gerador de Documentos e, em seguida, selecione Criar função.
  2. 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 Compartimento da VCN: para selecionar uma rede VCN em outro compartimento.
      • Sub-redes: A sub-rede (ou sub-redes, até três no máximo) na qual executar funções. Opcionalmente, selecione Compartimento de sub-redes: para selecionar uma sub-rede em 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.
      • Tags: 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ê deve 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 essa opção ou pergunte a um administrador. Você pode aplicar tags posteriormente.
  3. 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.
  4. Configure a memória da função e os valores de timeout da seguinte forma:
    • Memória (em MBs): A quantidade máxima de memória que a função pode usar durante a execução, em megabytes. Esta é a memória disponível para a imagem da função. (Padrão: 512 MB)
    • Timeout (em segundos): A quantidade máxima de tempo que a função pode executar, em segundos. Se a função não for concluída no tempo especificado, o sistema cancelará a função. (Padrão: 300)
  5. (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.

  6. Defina os parâmetros de configuração da função, conforme descrito em Opções de Configuração.
  7. Opcionalmente, informe qualquer tag na seção Tags. 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ê deve 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 essa opção ou pergunte a um administrador. Você pode aplicar tags posteriormente.
  8. 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 manage objects 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.

Cargas Úteis de Solicitação e Resposta HTTP

Para obter uma lista completa de valores de solicitação e resposta, consulte API do Gerador de Documentos de Função Pré-Criada.

Exemplo de Solicitações e Respostas

Exemplo 1: Gerando um único PDF

Solicitação:

{
  "requestType": "SINGLE",
  "tagSyntax": "DOCGEN_1_0",
  "data": {    
    "source": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/movies.json"
  },
  "template": {
    "source": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/movies.docx"
  },
  "output": {
    "target": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/movies.pdf",
    "contentType": "application/pdf"
   }
}

Resposta - sucesso:

{
  "responseType": "SINGLE",
  "code": 200,
  "status": "OK",
  "document": {
    "type": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/movies.pdf",
    "contentType": "application/pdf"
  },
  "metadata": {
    "version": "1.0",
    "configurationParameters": {
      "FN_FN_NAME": "docgen",
      "FN_APP_NAME": "docgen-app",
      "FN_TYPE": "sync",
      "FN_APP_ID": "ocid1.fnapp.oc1.phx.example...63m5hsmzzz",
      "OCI_REGION_METADATA": "{\"realmDomainComponent\":\"oraclecloud.com\",\"realmKey\":\"oc1\",\"regionIdentifier\":\"us-phoenix-1\",\"regionKey\":\"PHX\"}",
      "FN_FN_ID": "ocid1.fnfunc.oc1.phx.example...h523viuzzz",
      "FN_MEMORY": "512"
    }
  }
}

Resposta - falha:

{
  "responseType": "ERROR",
  "code": "400",
  "status": "InvalidParameters",
  "error": "No template has been specified.",
  "metadata": {
    "version": "1.0",
    "configurationParameters": {
      "FN_FN_NAME": "docgen",
      "FN_APP_NAME": "docgen-app",
      "FN_TYPE": "sync",
      "FN_APP_ID": "ocid1.fnapp.oc1.phx.example...63m5hsmzzz",
      "OCI_REGION_METADATA": "{\"realmDomainComponent\":\"oraclecloud.com\",\"realmKey\":\"oc1\",\"regionIdentifier\":\"us-phoenix-1\",\"regionKey\":\"PHX\"}",
      "FN_FN_ID": "ocid1.fnfunc.oc1.phx.example...h523viuzzz",
      "FN_MEMORY": "512"
    }
  }
}

Para obter mais informações, consulte:

Exemplo 2: Gerando vários PDFs - dados especificados em linha

Solicitação:

{
  "requestType": "BATCH",
  "tagSyntax": "DOCGEN_1_0",
   "data": {
    "source": "INLINE",
    "content": [{"name":"John"},{"name":"Monica"}]
  },
  "template": {
    "source": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/Letters.docx",
    "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
  },
  "output": {
    "target": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/Letters{documentId}.pdf",
    "contentType": "application/pdf",
    "storageTier": "INFREQUENT_ACCESS"
   }
}

Resposta - sucesso:

{
  "responseType": "BATCH",
  "code": 207,
  "status": "Multi-Status",
  "documents": [
    {
      "documentId": 1,
      "code": 200,
      "status": "OK",
      "document": {
        "type": "OBJECT_STORAGE",
        "namespace": "my_namespace",
        "bucketName": "my_bucket",
        "objectName": "my_folder/Letters1.pdf",
        "contentType": "application/pdf",
        "storageTier": "INFREQUENT_ACCESS"    
      }
    },
    {
      "documentId": 2,
      "code": 200,
      "status": "OK",
      "document": {
        "type": "OBJECT_STORAGE",
        "namespace": "my_namespace",
        "bucketName": "my_bucket",
        "objectName": "my_folder/Letters2.pdf",
        "contentType": "application/pdf",
        "storageTier": "INFREQUENT_ACCESS"    
      }
    }
  ],
  "metadata": {
    "version": "1.0",
    "configurationParameters": {
      "FN_FN_NAME": "docgen",
      "FN_APP_NAME": "docgen-app",
      "FN_TYPE": "sync",
      "FN_APP_ID": "ocid1.fnapp.oc1.phx.example...63m5hsmzzz",
      "OCI_REGION_METADATA": "{\"realmDomainComponent\":\"oraclecloud.com\",\"realmKey\":\"oc1\",\"regionIdentifier\":\"us-phoenix-1\",\"regionKey\":\"PHX\"}",
      "FN_FN_ID": "ocid1.fnfunc.oc1.phx.example...h523viuzzz",
      "FN_MEMORY": "512"
    }
  }
 }

Para obter mais informações, consulte:

Nomes de Documento na Saída de Lote

Com "responseType": "BATCH", vários documentos são produzidos. Você pode controlar a nomeação desses documentos usando o obrigatório{documentId} no nome do documento.

Formato output.objectName Descrição Exemplos
invoice{documentId}.pdf Sem preenchimento. Começa em 1. invoice1.pdf, invoice2.pdf
invoice{documentId|zeroPadding=auto}.pdf Preenchimento automático com base no número de documentos em lote. Começa em 1. invoice01.pdf ... invoice10.pdf
invoice{documentId|firstId=51}.pdf Nenhum preenchimento com zeros. Começa às 51. invoice51.pdf, invoice52.pdf
invoice{documentId|firstId=51,zeroPadding=5}.pdf Preenchimento esquerdo de 5 dígitos com 0. Começa às 51. invoice00051.pdf, invoice00052.pdf
invoice{documentId|zeroPadding=5}.pdf Preenchimento esquerdo de 5 dígitos com 0. Começa em 1. invoice00001.pdf, invoice00002.pdf

Tipos de Documento Compatíveis

Do Modelo (contentType) Para Saída (contentType)
Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document) PDF (inscrição/PDF)
Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document) Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document)
Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) PDF (inscrição/PDF)
Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)

Fontes

As seguintes fontes estão disponíveis ao gerar um PDF:

  • Caladeia
  • Cookie
  • Carlito
  • DejaVu
  • LiberationMono (Transportadora)
  • LiberationSans (Arial)
  • LiberationSerif (Times New Roman)
  • NotoSans-Preto
  • NotoSans-BoldItalic
  • NotoSans-ExtraLight
  • NotoSans-Luz
  • NotoSans-MediumItalic
  • NotoSans-SemiBoldItalic
  • NotoSans-BlackItalic
  • NotoSans-ExtraBold
  • NotoSans-ExtraLightItalic
  • NotoSans-LightItalic
  • NotoSans - Regular
  • NotoSans-Fino
  • NotoSans - Negrito
  • NotoSans-ExtraBoldItalic
  • NotoSans-Itálico
  • NotoSans-Médio
  • NotoSans-SemiBold
  • NotoSans-ThinItalic
  • NotoSansJP - Negrito
  • NotoSansJP - Regular
  • NotoSansKR - Regular
  • NotoSansKR - Negrito
  • NotoSansSC - Regular
  • NotoSansSC - Negrito
  • NotoSansTC - Regular
  • NotoSansTC-Bold.otf
  • NotoSansArabic - Regular
  • NotoSansArabic - Negrito
  • NotoSansHebrew - Regular
  • NotoSansHebrew - Negrito
  • NotoSerif - Negrito
  • NotoSerif-BoldItalic
  • NotoSerif-Itálico
  • NotoSerif - Regular
  • OracleSans - Negrito
  • OracleSans - Regular
  • Oswald-Bold
  • Oswald-ExtraLight
  • Oswald-Light
  • Oswald-Medium
  • Oswald-Regular
  • Oswald-SemiBold

Se você precisar de uma fonte que não esteja nesta lista, poderá especificar um pacote de fontes na solicitação Gerador de documentos. Um pacote de fontes é um arquivo zip que contém arquivos .ttf e .otf que serão usados durante a geração de PDF. Para obter um exemplo, consulte RequestSingle Reference.

Protegendo um Documento PDF Gerado com uma Senha

Ao gerar um único PDF (com "requestType": "SINGLE") ou vários PDFs (com "requestType": "BATCH"), você pode especificar uma senha para proteger o PDF gerado. Depois de gerar o PDF, a senha deve ser inserida antes que o PDF possa ser aberto.

Para especificar a senha para proteger o PDF gerado, inclua "documentOpenPassword" : "<a-password>" em uma seção "options" da solicitação. O valor de <a-password> deve ser uma string alfanumérica entre 1 e 127 caracteres.

Por exemplo:

{
  "requestType": "SINGLE",
  "tagSyntax": "DOCGEN_1_0",
  "data": ...  
  "template": ...
  "output": ...
  "options": {
    "documentOpenPassword" : "MyPasswordToOpenTheDocument"
  }
}

Tags de Modelo do Gerador de Documentos

Para obter uma lista completa de tags de modelo, consulte:

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 Gerador de Documentos

Código do Status Descrição
200 Bem-sucedido
207 Para responseType=BATCH, verifique o código de resposta de cada documento individual.
400 Erro de validação ou erro de processamento. Se um erro ObjectNotFound for retornado, certifique-se de que a sub-rede que contém a função tenha acesso ao serviço Object Storage.
500 erro interno.

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 Documentos é semelhante à seguinte:

"PBF | Document Generator | INFO | 2023-08-31T20:19:51.181593Z | 2. LOG001 - Setting Log Level to : DEBUG"