Función de generador de documentos

Descubra cómo utilizar la función predefinida Generador de documentos en OCI Functions para generar documentos basados en plantillas de Office y datos JSON.

Casos de Uso Común

Las formas comunes de utilizar la función Generador de documentos incluyen:

Coloque una plantilla de Office y datos JSON en el almacenamiento de objetos y llame directamente a la función para generar documentos PDF y almacenar los resultados en el almacenamiento de objetos.

Los servicios relacionados con la función Generador de documentos incluyen:

Almacenamiento de objetos

Requisitos y recomendaciones

A continuación, se muestran las mejores prácticas al utilizar esta función incorporada:

La VCN enlazada a la aplicación facilita el acceso a otros servicios de OCI mediante un gateway de servicio, un gateway de Internet o un gateway de NAT.
Defina el tamaño de memoria por defecto en 512 MB para la mayoría de las tareas. El uso de conjuntos de datos más grandes, la agrupación de fuentes o el uso del procesamiento por lotes pueden requerir más memoria.
Para el procesamiento por lotes, establezca el timeout de la función predefinida en 300 segundos.

Configuración de la Función del Generador de Documentos

Para configurar una función del generador de documentos, realice los siguientes pasos:

En la página Funciones predefinidas, seleccione Generador de documentos y, a continuación, seleccione Crear función.
Configure el nombre, el compartimento y la aplicación de la siguiente forma:
- Nombre: nombre que desea para la nueva función. El nombre debe comenzar con una letra o guion bajo, seguido de letras, números, guiones o guiones bajos. La longitud puede abarcar entre 1 y 255 caracteres. Evite introducir información confidencial.
  Para crear la función en un compartimento diferente, seleccione Cambiar compartimento.
- Aplicación: seleccione la aplicación en la que desea crear la función.
  Si aún no existe una aplicación adecuada en el compartimento actual, seleccione Crear nueva aplicación y especifique los siguientes detalles:
  - Nombre: nombre de la nueva aplicación. Evite introducir información confidencial.
  - VCN: la VCN (red virtual en la nube) en la que se ejecutan funciones en la aplicación. Opcionalmente, seleccione Compartimento de VCN: para seleccionar un VCN de otro compartimento.
  - Subredes: subred (o subredes, hasta un máximo de tres) en las que ejecutar funciones. Opcionalmente, seleccione Compartimento de subredes: para seleccionar una subred de un compartimento diferente.
  - Unidad: arquitectura de procesador de las instancias informáticas en las que desplegar y ejecutar funciones en la aplicación. Todas las funciones de la aplicación se despliegan y ejecutan en instancias informáticas con la misma arquitectura. La imagen de la función debe contener las dependencias necesarias para la arquitectura que seleccione.
  - Etiquetas: si tiene permisos para crear un recurso, también tiene permisos para aplicar etiquetas de formato libre a ese recurso. Etiquetas Para aplicar una etiqueta defined, debe tener permisos para utilizar el espacio de nombres de la etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.
Configure la política de IAM para funciones predefinidas.

Por defecto, OCI Functions crea un grupo dinámico y una política de IAM con las sentencias de política necesarias para ejecutar la función predefinida. No realice cambios para aceptar el comportamiento predeterminado.

Si no desea que OCI Functions cree automáticamente el grupo dinámico y la política, seleccione No crear un grupo dinámico ni una política de IAM.

Importante

Si selecciona la opción No crear un grupo dinámico y una política de IAM, debe definir el grupo dinámico y la política de IAM usted mismo. Para obtener más información, consulte Permisos.
Configure la memoria de la función y los valores de timeout de la siguiente manera:
- Memoria (en MB): cantidad máxima de memoria que la función puede utilizar mientras se ejecuta, en megabytes. Esta es la memoria disponible para la imagen de la función. (Valor predeterminado: 512 MB)
- Timeout (en segundos): cantidad máxima de tiempo durante la que se puede ejecutar la función, en segundos. Si la función no se completa en el tiempo especificado, el sistema cancela la función. (Valor por Defecto: 300)
(Opcional) Configure la simultaneidad aprovisionada para minimizar los retrasos iniciales al llamar a la función especificando un número mínimo de llamadas a funciones simultáneas para las que desea que la infraestructura de ejecución esté disponible constantemente. (Valor por defecto: No activado)

Si se selecciona, especifique el número de unidades de simultaneidad aprovisionadas asignadas a esta función. Por defecto: 10.

Para obtener más información sobre la simultaneidad aprovisionada, consulte Reducing Initial Latency Using Provisioned Concurrency.
Defina los parámetros de configuración de la función como se describe en Opciones de Configuración.
Opcionalmente, introduzca cualquier etiqueta en la sección Etiquetas. Si tiene permisos para crear un recurso, también tiene permisos para aplicar etiquetas de formato libre a dicho recurso. Para aplicar una etiqueta defined, debe tener permisos para utilizar el espacio de nombres de la etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.
Haga clic en Crear.

El cuadro de diálogo de despliegue muestra las tareas para desplegar la función (consulte Finalización del despliegue de funciones incorporadas).

Opciones de Configuración

Parámetros de Configuración


Nombre	Descripción	necesario
`PBF_LOG_LEVEL`	Nivel de registro, las opciones son `DEBUG`, `INFO`, `WARN` y `ERROR`. El valor por defecto es `INFO`.	No

Permisos

La ejecución de una función requiere determinadas políticas de IAM. Si ha seleccionado la opción No crear un grupo dinámico y una política de IAM al crear la función, debe definir el grupo dinámico y la política de IAM usted mismo.

Para definir las políticas adecuadas, realice los siguientes pasos:

Crear un grupo dinámico con la regla:

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

Configure una política de IAM mediante el grupo dinámico:

Allow dynamic-group <dynamic-group-name> to manage objects in compartment <compartment-name>

Nota

Sustituya <function-ocid> por el OCID de la función que ha creado en los pasos anteriores.

Nota

Sustituya <dynamic-group-name> por el nombre del grupo dinámico que ha creado mediante el OCID de la función.

Nota

Sustituya <compartment_ocid> por el OCID del compartimento que contiene la función.

Llamando a esta función

Puede llamar a la función de las siguientes formas:

Llame a la función directamente como se documenta en Llamada a funciones creando un cuerpo de solicitud como se muestra en el siguiente ejemplo de JSON.

Cargas útiles de respuesta y solicitud HTTP

Para obtener una lista completa de los valores de solicitud y respuesta, consulte API del generador de documentos de función creada previamente.

Ejemplo de solicitudes y respuestas

Ejemplo 1: Generación de un único PDF

Solicitud:

{
  "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"
   }
}

Respuesta: satisfactoria:

{
  "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"
    }
  }
}

Respuesta: fallo:

{
  "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 obtener más información, consulte:

Ejemplo 2: Generación de varios PDF: datos especificados en línea

Solicitud:

{
  "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"
   }
}

Respuesta: satisfactoria:

{
  "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 obtener más información, consulte:

Nombres de documento en salida por lotes

Con "responseType": "BATCH", se generan varios documentos. Puede controlar la nomenclatura de estos documentos mediante required{documentId} en el nombre del documento.


Formato output.objectName	Descripción	Ejemplos
`invoice{documentId}.pdf`	No hay relleno. Empieza a las 1.	invoice1.pdf, invoice2.pdf
`invoice{documentId\|zeroPadding=auto}.pdf`	Relleno automático basado en el número de documentos en lote. Empieza a las 1.	invoice01.pdf ... invoice10.pdf
`invoice{documentId\|firstId=51}.pdf`	Sin relleno cero. Empieza en 51.	invoice51.pdf, invoice52.pdf
`invoice{documentId\|firstId=51,zeroPadding=5}.pdf`	Relleno izquierdo de 5 dígitos con 0. Empieza en 51.	invoice00051.pdf, invoice00052.pdf
`invoice{documentId\|zeroPadding=5}.pdf`	Relleno izquierdo de 5 dígitos con 0. Empieza a las 1.	invoice00001.pdf, invoice00002.pdf

Tipos de Documento Soportados


De plantilla (contentType)	A salida (contentType)
Microsoft Word >= 2010 (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`)	PDF (aplicación/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 (aplicación/PDF)
Microsoft Excel >= 2010 (`application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)	Microsoft Excel >= 2010 (`application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)

Fuentes

Las siguientes fuentes están disponibles al generar un PDF:

Caladea
Cookie
Carlito
DejaVu
LiberationMono (Correo)
LiberationSans (Arial)
LiberationSerif (Times New Roman)
NotoSans: negro
NotoSans-BoldItalic
NotoSans-ExtraLight
NotoSans: luz
NotoSans-MediumItalic
NotoSans-SemiBoldItalic
NotoSans-BlackItalic
NotoSans-ExtraBold
NotoSans-ExtraLightItalic
NotoSans-LightItalic
NotoSans: regular
NotoSans: ligero
NotoSans: negrita
NotoSans-ExtraBoldItalic
NotoSans: cursiva
NotoSans: medio
NotoSans-SemiBold
NotoSans-ThinItalic
NotoSansJP: negrita
NotoSansJP: regular
NotoSansKR: regular
NotoSansKR: negrita
NotoSansSC: regular
NotoSansSC: negrita
NotoSansTC: regular
NotoSansTC-Bold.otf
NotoSansArabic: regular
NotoSansArabic: negrita
NotoSansHebrew: regular
NotoSansHebrew: negrita
NotoSerif: negrita
NotoSerif-BoldItalic
NotoSerif: cursiva
NotoSerif: regular
OracleSans: negrita
OracleSans: regular
Oswald-Bold
Oswald-ExtraLight
Oswald-Light
Oswald-Medium
Oswald-Regular
Oswald-SemiBold

Si necesita una fuente que no esté en esta lista, puede especificar un grupo de fuentes en la solicitud del Generador de documentos. Un paquete de fuentes es un archivo zip que contiene los archivos .ttf y .otf que se utilizarán durante la generación de PDF. Para obtener un ejemplo, consulte RequestSingle Reference.

Protección de un Documento PDF Generado con una Contraseña

Al generar un solo PDF (con "requestType": "SINGLE") o varios PDF (con "requestType": "BATCH"), puede especificar una contraseña para proteger el PDF generado. Una vez generado el PDF, es necesario introducir la contraseña para poder abrir el PDF.

Para especificar la contraseña para proteger el PDF generado, incluya "documentOpenPassword" : "<a-password>" en una sección "options" de la solicitud. El valor de <a-password> debe ser una cadena alfanumérica de entre 1 y 127 caracteres de longitud.

Por ejemplo:

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

Etiquetas de plantilla de generador de documentos

Para obtener una lista completa de las etiquetas de plantilla, consulte:

Solución de Problemas

Códigos de estado comunes de OCI Functions

En la siguiente tabla se resumen los errores comunes de OCI Functions que puede encontrar al trabajar con funciones predefinidas:


Código de Error	Mensaje de Error	Acción
200	Correcto	Ninguna.
404	NotAuthorizedOrNotFound	Verifique que las políticas necesarias estén configuradas (consulte Ejecución de comandos de la CLI de Fn Project devuelve un error 404).
444	Timeout	La conexión entre el cliente y OCI Functions se ha interrumpido durante la ejecución de la función (consulte La llamada a una función hace que el cliente informe de un timeout y se muestra un error 444 en los logs de la función). Un reintento podría resolver el problema. Tenga en cuenta que la mayoría de los clientes tienen un timeout interno de 60 segundos. Incluso cuando el tiempo de espera de la función predefinida se establece en 300 segundos, puede ser necesario lo siguiente: Al utilizar la CLI de OCI: utilice --read-timeout 300 Al utilizar el SDK de OCI: defina el timeout de lectura en 300 al crear el cliente Al utilizar DBMS_CLOUD.SEND_REQUEST: utilice UTL_HTTP.set_transfer_timeout(300); Para obtener más información, consulte Llamada a funciones.
502 504	(varios)	La mayoría de los problemas devuelven un código de estado 502 (consulte Llamada a una función devuelve un mensaje de fallo de función y un error 502). Se puede resolver un error 502 con el mensaje "error receive function response" mediante el aumento de la asignación de memoria. Un 502 puede ocurrir ocasionalmente cuando la función está en algún estado transitorio. Un reintento podría resolver el problema.

Para identificar aún más la causa, active las funciones de registro para la función predefinida (consulte Almacenamiento y visualización de logs de funciones). Para obtener información detallada sobre la solución de problemas de una función, consulte Solución de problemas de OCI Functions.

Códigos de estado de función creados previamente por el generador de documentos


Código de Estado	Descripción
200	Correcto
207	Para responseType=BATCH, verifique el código de respuesta de cada documento individual.
400	Error de validación o error de procesamiento. Si se devuelve un error ObjectNotFound, asegúrese de que la subred que contiene la función tenga acceso al servicio Object Storage.
500	Error interno.

Para identificar aún más la causa, active las funciones de registro para la función predefinida (consulte Almacenamiento y visualización de logs de funciones).

Consejos de análisis de logs

Todas las funciones predefinidas proporcionan una opción para especificar el nivel de registro como parámetro de configuración. Puede definir el nivel de registro en DEBUG para obtener más información.

Dado que una aplicación tiene varias funciones, las entradas del log de funciones predefinidas se identifican con el prefijo "PBF | <PBF NAME> ".

Por ejemplo, una entrada de registro para la función creada previamente por el generador de documentos tiene un aspecto similar al siguiente:

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

Documentación de Oracle Cloud Infrastructure