Oracle Cloud Infrastructure - Dokumentation

Dokumentgeneratorfunktion

Erfahren Sie, wie Sie mit der vordefinierten Funktion Document Generator in OCI Functions Dokumente basierend auf Office-Vorlagen und JSON-Daten generieren können.

Allgemeine Verwendungsszenarios

Zu den allgemeinen Möglichkeiten, die Document Generator-Funktion zu verwenden, gehören:

  • Platzieren Sie eine Office-Vorlage und JSON-Daten im Objektspeicher, und rufen Sie die Funktion direkt auf, um PDF-Dokumente zu generieren und die Ergebnisse im Objektspeicher zu speichern.

Zu den Services im Zusammenhang mit der Funktion "Dokumentgenerator" gehören:

Voraussetzungen und Empfehlungen

Im Folgenden finden Sie Best Practices bei der Verwendung dieser vordefinierten Funktion:

  • Stellen Sie sicher, dass das mit der Anwendung verknüpfte VCN den Zugriff auf andere OCI-Services über ein Servicegateway, ein Internetgateway oder ein NAT-Gateway erleichtert.
  • Legen Sie für die meisten Aufgaben die Standardspeichergröße auf 512 MB fest. Wenn Sie größere Datasets verwenden, Schriftarten bündeln oder Batch-Verarbeitung verwenden, ist möglicherweise mehr Speicher erforderlich.
  • Legen Sie für die Batchverarbeitung den vordefinierten Funktionstimeout auf 300 Sekunden fest.

Funktion "Dokumentgenerator" konfigurieren

Um eine Dokumentgeneratorfunktion zu konfigurieren, gehen Sie wie folgt vor:

  1. Wählen Sie auf der Seite Vordefinierte Funktionen die Option Dokumentgenerator und dann Funktion erstellen aus.
  2. Konfigurieren Sie Name, Compartment und Anwendung wie folgt:
    • Name: Geben Sie einen Namen Ihrer Wahl für die neue Funktion ein. Der Name muss mit einem Buchstaben oder Unterstrich beginnen und darf nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten. Die zulässige Länge beträgt 1–255 Zeichen. Geben Sie keine vertraulichen Informationen ein.

      Um die Funktion in einem anderen Compartment zu erstellen, wählen Sie Compartment ändern aus.

    • Anwendung: Wählen Sie die Anwendung aus, in der Sie die Funktion erstellen möchten.

      Wenn noch keine geeignete Anwendung im aktuellen Compartment vorhanden ist, wählen Sie Neue Anwendung erstellen aus, und geben Sie die folgenden Details an:

      • Name: Ein Name für die neue Anwendung. Geben Sie keine vertraulichen Informationen ein.
      • VCN: Das VCN (virtuelles Cloud-Netzwerk), in dem Funktionen in der Anwendung ausgeführt werden sollen. Wählen Sie optional VCN-Compartment: aus, um ein VCN in einem anderen Compartment auszuwählen.
      • Subnetz: Das Subnetz (oder die Subnetze, bis zu drei) in dem Funktionen ausgeführt werden sollen. Wählen Sie optional Subnetz-Compartment: aus, um ein Subnetz aus einem anderen Compartment auszuwählen.
      • Ausprägung: Die Prozessorarchitektur der Compute-Instanzen, auf denen Funktionen in der Anwendung bereitgestellt und ausgeführt werden sollen. Alle Funktionen in der Anwendung werden bereitgestellt und auf Compute-Instanzen mit derselben Architektur ausgeführt. Das Abbild der Funktion muss die erforderlichen Abhängigkeiten für die ausgewählte Architektur enthalten.
      • Tags: Wenn Sie über Berechtigungen zum Erstellen von Ressourcen verfügen, können Sie auch Freiformtags auf diese Ressource anwenden. Um ein definiertes Tag anzuwenden, benötigen Sie Die Berechtigungen zum Verwenden des Tag-Namespace. Weitere Informationen zum Tagging finden Sie unter Ressourcentags. Wenn Sie nicht sicher sind, ob Tags angewendet werden sollen, überspringen Sie diese Option, oder fragen Sie einen Administrator. Sie können Tags später anwenden.
  3. Konfigurieren Sie die IAM-Policy für vordefinierte Funktionen.

    Standardmäßig erstellt OCI Functions eine dynamische Gruppe und eine IAM-Policy mit den Policy-Anweisungen, die zum Ausführen der vordefinierten Funktion erforderlich sind. Sie haben folgende Möglichkeiten, um fortzufahren:

    • Wenn OCI Functions die dynamische Gruppe und Policy automatisch erstellen soll, nehmen Sie keine Änderungen vor, um das Standardverhalten zu akzeptieren.
    • Wenn OCI Functions die dynamische Gruppe und Policy nicht automatisch erstellen soll, wählen Sie Keine dynamische Gruppe und IAM-Policy erstellen aus.
    Wichtig

    Wenn Sie die Option Keine dynamische Gruppe und IAM-Policy erstellen auswählen, müssen Sie die dynamische Gruppe und die IAM-Policy selbst definieren. Weitere Informationen finden Sie unter Berechtigungen.
  4. Konfigurieren Sie den Funktionsspeicher und die Timeoutwerte wie folgt:
    • Arbeitsspeicher (in MB): Der maximale Arbeitsspeicher, den die Funktion während der Ausführung in Megabyte nutzen kann. Dies ist der Speicher, der dem Funktionsbild zur Verfügung steht. (Standard: 512 MB)
    • Timeout (in Sekunden): Die maximale Zeit, für die die Funktion ausgeführt werden kann, in Sekunden. Wenn die Funktion nicht innerhalb der angegebenen Zeit abgeschlossen wird, bricht das System die Funktion ab. (Standardwert: 300)
  5. (Optional) Konfigurieren Sie Provisioned Concurrency, um anfängliche Verzögerungen beim Aufrufen der Funktion zu minimieren, indem Sie eine Mindestanzahl gleichzeitiger Funktionsaufrufe angeben, für die Sie die Ausführungsinfrastruktur ständig verfügbar machen möchten. (Standard: Nicht aktiviert)

    Wenn diese Option ausgewählt ist, geben Sie die Anzahl der bereitgestellten Nebenläufigkeitseinheiten an, die dieser Funktion zugewiesen sind. Standard: 10.

    Weitere Informationen zum bereitgestellten gleichzeitigen Zugriff finden Sie unter Anfängliche Latenz mit bereitgestelltem gleichzeitigem Zugriff reduzieren.

  6. Legen Sie die Konfigurationsparameter der Funktion wie unter Konfigurationsoptionen beschrieben fest.
  7. Geben Sie optional beliebige Tags in den Abschnitt Tags ein. Wenn Sie über Berechtigungen zum Erstellen von Ressourcen verfügt, sind Sie auch berechtigt: Freiformtags auf diese Ressource anwenden. Um ein definiertes Tag anzuwenden, benötigen Sie Die Berechtigungen zum Verwenden des Tag-Namespace. Weitere Informationen zum Tagging finden Sie unter Ressourcentags. Wenn Sie nicht sicher sind, ob Tags angewendet werden sollen, überspringen Sie diese Option, oder fragen Sie einen Administrator. Sie können Tags später anwenden.
  8. Klicken Sie auf Erstellen.

Im Dialogfeld "Bereitstellen" werden die Aufgaben zum Bereitstellen der Funktion angezeigt (siehe Vordefiniertes Funktions-Deployment beenden).

Konfigurationsoptionen

Konfigurationsparameter

Name Beschreibung Erforderlich
PBF_LOG_LEVEL Logging-Ebene, Optionen sind DEBUG, INFO, WARN und ERROR. Der Standardwert ist INFO. Nein

Berechtigungen

Für die Ausführung einer Funktion sind bestimmte IAM-Policys erforderlich. Wenn Sie beim Erstellen der Funktion die Option Keine dynamische Gruppe und IAM-Policy erstellen ausgewählt haben, müssen Sie die dynamische Gruppe und die IAM-Policy selbst definieren.

Um die richtigen Policys festzulegen, führen Sie die folgenden Schritte aus:

  • Dynamische Gruppe mit der Regel erstellen: 
    ALL {resource.id = '<function_ocid>' , resource.compartment.id = '<compartment_ocid>'}
  • Konfigurieren Sie eine IAM-Policy mit der dynamischen Gruppe: 
    Allow dynamic-group <dynamic-group-name> to manage objects in compartment <compartment-name>
Hinweis

Ersetzen Sie <function-ocid> durch die OCID der Funktion, die Sie in den vorherigen Schritten erstellt haben.
Hinweis

Ersetzen Sie <dynamic-group-name> durch den Namen der dynamischen Gruppe, die Sie mit der OCID der Funktion erstellt haben.
Hinweis

Ersetzen Sie <compartment_ocid> durch die OCID des Compartments, das die Funktion enthält.

Diese Funktion wird aufgerufen

Sie können die Funktion wie folgt aufrufen:

  • Rufen Sie die Funktion direkt auf, wie unter Funktionen aufrufen beschrieben, indem Sie einen Anforderungstext erstellen, wie im folgenden JSON-Beispiel dargestellt.

HTTP-Anforderungs- und Antwort-Payloads

Eine vollständige Liste der Anforderungs- und Antwortwerte finden Sie unter Dokumentgenerator-API für vorkonfigurierte Funktionen.

Beispielanforderungen und -antworten

Beispiel 1: Generieren einer einzelnen PDF-Datei

Anfordern:

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

Antwort - Erfolg:

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

Antwort - Fehler:

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

Weitere Informationen finden Sie unter:

Beispiel 2: Mehrere PDFs generieren - Inline angegebene Daten

Anfordern:

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

Antwort - Erfolg:

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

Weitere Informationen finden Sie unter:

Dokumentnamen in der Batchausgabe

Mit "responseType": "BATCH" werden mehrere Dokumente erstellt. Sie können die Benennung dieser Dokumente mit der erforderlichen{documentId} im Dokumentnamen steuern.

output.objectName-Format Beschreibung Beispiele
invoice{documentId}.pdf Kein Padding. Beginnt bei 1. invoice1.pdf, invoice2.pdf
invoice{documentId|zeroPadding=auto}.pdf Automatisches Auffüllen basierend auf der Anzahl der Dokumente im Batch. Beginnt bei 1. invoice01.pdf ... invoice10.pdf
invoice{documentId|firstId=51}.pdf Kein Auffüllen mit Nullen. Beginnt bei 51. invoice51.pdf, invoice52.pdf
invoice{documentId|firstId=51,zeroPadding=5}.pdf 5 Stellen links mit 0 auffüllen. Beginnt bei 51. invoice00051.pdf, invoice00052.pdf
invoice{documentId|zeroPadding=5}.pdf 5 Stellen links mit 0 auffüllen. Beginnt bei 1. invoice00001.pdf, invoice00002.pdf

Unterstützte Dokumenttypen

Von Vorlage (contentType) In Ausgabe (contentType)
Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document) PDF (Antrag/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 (Anwendung/PDF)
Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)

Schriften

Die folgenden Schriftarten sind beim Generieren einer PDF verfügbar:

  • Caladea
  • Cookie
  • Carlito
  • DejaVu
  • LiberationMono (Kurier)
  • LiberationSans (Arial)
  • LiberationSerif (Times New Roman)
  • NotoSans-Schwarz
  • NotoSans-BoldItalic
  • NotoSans-ExtraLight
  • NotoSans-Leicht
  • NotoSans-MediumItalic
  • NotoSans-SemiBoldItalic
  • NotoSans-BlackItalic
  • NotoSans-ExtraBold
  • NotoSans-ExtraLightItalic
  • NotoSans-LightItalic
  • NotoSans - Regulär
  • NotoSans-Thin
  • NotoSans-Fett
  • NotoSans-ExtraBoldItalic
  • NotoSans - Kursiv
  • NotoSans-Mittel
  • NotoSans-SemiBold
  • NotoSans-ThinItalic
  • NotoSansJP-Fett
  • NotoSansJP - Regulär
  • NotoSansKR - Regulär
  • NotoSansKR-Fett
  • NotoSansSC - Regulär
  • NotoSansSC-Fett
  • NotoSansTC - Regulär
  • NotoSansTC-Bold.otf
  • NotoSansArabic - Regulär
  • NotoSansArabic-Fett
  • NotoSansHebrew - Regulär
  • NotoSansHebrew-Fett
  • NotoSerif-Fett
  • NotoSerif-BoldItalic
  • NotoSerif - Kursiv
  • NotoSerif - Regulär
  • OracleSans-Fett
  • OracleSans - Regulär
  • Oswald-Bold
  • Oswald-ExtraLight
  • Oswald-Licht
  • Oswald-Mittel
  • Oswald-Regular
  • Oswald-SemiBold

Wenn Sie eine Schriftart benötigen, die nicht in dieser Liste enthalten ist, können Sie ein Schriftart-Bundle in der Dokumentgenerator-Anforderung angeben. Ein Schriftart-Bundle ist eine ZIP-Datei mit den Dateien .ttf und .otf, die während der PDF-Generierung verwendet werden. Ein Beispiel finden Sie in der RequestSingle-Referenz.

Schützen eines generierten PDF-Dokuments mit einem Passwort

Wenn Sie eine einzelne PDF-Datei (mit "requestType": "SINGLE") oder mehrere PDF-Dateien (mit "requestType": "BATCH") generieren, können Sie ein Kennwort zum Schutz der generierten PDF-Datei angeben. Nachdem die PDF generiert wurde, muss das Passwort eingegeben werden, bevor die PDF geöffnet werden kann.

Um das Kennwort zum Schutz der generierten PDF anzugeben, fügen Sie "documentOpenPassword" : "<a-password>" in einen "options"-Abschnitt der Anforderung ein. Der Wert von <a-password> muss eine alphanumerische Zeichenfolge mit einer Länge zwischen 1 und 127 Zeichen sein.

Beispiel:

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

Tags für Dokumentgeneratorvorlage

Eine vollständige Liste der Template-Tags finden Sie unter:

Fehlersuche

Allgemeine Statuscodes für OCI Functions

In der folgenden Tabelle werden allgemeine OCI Functions-Fehler zusammengefasst, die bei der Arbeit mit vordefinierten Funktionen auftreten können:

Fehlercode Fehlermeldung Maßnahme
200 Erfolgreich -
404 NotAuthorizedOrNotFound Stellen Sie sicher, dass die erforderlichen Policys konfiguriert sind (siehe Ausführen von Fn-Projekt-CLI-Befehlen gibt einen 404-Fehler zurück).
444 Timeout

Die Verbindung zwischen dem Client und OCI Functions wurde während der Funktionsausführung unterbrochen (siehe Wenn Sie eine Funktion aufrufen, meldet der Client einen Timeout, und in den Logs der Funktion wird ein 444-Fehler angezeigt). Ein erneuter Versuch könnte das Problem lösen.

Beachten Sie, dass die meisten Clients einen inneren Timeout von 60 Sekunden aufweisen. Selbst wenn das vordefinierte Funktionstimeout auf 300 Sekunden gesetzt ist, ist möglicherweise Folgendes erforderlich:

  • Bei Verwendung der OCI-CLI: Verwenden Sie --read-timeout 300
  • Bei Verwendung des OCI-SDK: Legen Sie beim Erstellen des Clients den Lesetimeout auf 300 fest
  • Bei Verwendung von DBMS_CLOUD.SEND_REQUEST: Verwenden Sie UTL_HTTP.set_transfer_timeout(300);

Weitere Informationen finden Sie unter Funktionen aufrufen.
502 504 (verschiedene) Die meisten Probleme geben einen 502-Statuscode zurück (siehe Aufrufen einer Funktion gibt eine Meldung "Funktion nicht erfolgreich" und einen 502-Fehler zurück). Ein 502-Fehler mit der Meldung "Fehler beim Empfangen der Funktionsantwort" kann durch Erhöhung der Speicherzuweisung behoben werden. Eine 502 kann gelegentlich auftreten, wenn sich die Funktion in einem vorübergehenden Zustand befindet. Ein erneuter Versuch könnte das Problem lösen.

Um die Ursache weiter zu ermitteln, aktivieren Sie Loggingfeatures für die vordefinierte Funktion (siehe Funktionslogs speichern und anzeigen). Ausführliche Informationen zur Fehlerbehebung bei einer Funktion finden Sie unter Fehlerbehebung bei OCI Functions.

Vordefinierte Funktionsstatuscodes des Dokumentgenerators

Statuscode Beschreibung
200 Erfolgreich
207 Prüfen Sie bei einem responseType=BATCH den Antwortcode für jedes einzelne Dokument.
400 Validierungsfehler oder Verarbeitungsfehler. Wenn ein ObjectNotFound-Fehler zurückgegeben wird, stellen Sie sicher, dass das Subnetz, das die Funktion enthält, Zugriff auf den Object Storage-Service hat.
500 Interner Fehler.

Um die Ursache weiter zu ermitteln, aktivieren Sie Loggingfeatures für die vordefinierte Funktion (siehe Funktionslogs speichern und anzeigen).

Tipps zur Loganalyse

Alle vordefinierten Funktionen bieten eine Option zur Angabe der Logging-Ebene als Konfigurationsparameter. Sie können die Logging-Ebene auf DEBUG setzen, um weitere Informationen zu erhalten.

Da eine Anwendung mehrere Funktionen hat, werden die vordefinierten Funktionslogeinträge durch das Präfix "PBF | <PBF NAME>" identifiziert.

Beispiel: Ein Logeintrag für die vordefinierte Funktion "Dokumentgenerator" sieht ungefähr wie folgt aus:

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