ドキュメント・ジェネレータ関数
OCI FunctionsのDocument Generator組み込み関数を使用して、OfficeテンプレートとJSONデータに基づいてドキュメントを生成する方法をご覧ください。
一般的な使用方法のシナリオ
文書ジェネレータ機能の一般的な使用方法は次のとおりです。
- OfficeテンプレートおよびJSONデータをオブジェクト・ストレージに配置し、関数を直接起動してPDFドキュメントを生成し、結果をオブジェクト・ストレージに格納します。
文書ジェネレータ機能に関連するサービスは次のとおりです。
前提条件と推奨事項
この事前作成機能を使用する場合のベスト・プラクティスを次に示します。
- アプリケーションにリンクされたVCNが、サービス・ゲートウェイ、インターネット・ゲートウェイまたはNATゲートウェイを使用して、他のOCIサービスへのアクセスを容易にします。
- ほとんどのタスクでデフォルトのメモリー・サイズを512MBに設定します。大きいデータ・セットを使用したり、フォントをバンドルしたり、バッチ処理を使用したりすると、より多くのメモリーが必要になる場合があります。
- バッチ処理の場合は、事前に作成された関数のタイムアウトを300秒に設定します。
文書ジェネレータ機能の構成
構成オプション
構成パラメータ
名前 | 説明 | 必須 |
---|---|---|
PBF_LOG_LEVEL |
ロギング・レベル、オプションはDEBUG 、INFO 、WARN およびERROR です。デフォルトはINFO です。 |
いいえ |
権限
ファンクションを実行するには、特定のIAMポリシーが必要です。ファンクションの作成時に「動的グループおよびIAMポリシーを作成しない」オプションを選択した場合は、動的グループおよびIAMポリシーを自分で定義する必要があります。
適切なポリシーを設定するには、次のステップを実行します。
- ルールを使用して動的グループを作成します:
ALL {resource.id = '<function_ocid>' , resource.compartment.id = '<compartment_ocid>'}
- 動的グループを使用してIAMポリシーを構成します:
Allow dynamic-group <dynamic-group-name> to manage objects in compartment <compartment-name>
<function-ocid>
を、前のステップで作成したファンクションのOCIDに置き換えます。 <dynamic-group-name>
を、ファンクションのOCIDを使用して作成した動的グループの名前に置き換えます。<compartment_ocid>
を、ファンクションを含むコンパートメントのOCIDに置き換えます。この関数の起動
この関数は、次の方法で呼び出すことができます。
- 次のJSONの例に示すように、リクエスト本文を作成して、ファンクションの呼出しに記載されているとおりにファンクションを直接起動します。
HTTPリクエストおよびレスポンスのペイロード
リクエスト値とレスポンス値の完全なリストは、事前作成済ファンクション・ドキュメント・ジェネレータAPIを参照してください。
リクエストとレスポンスの例
例1: 単一のPDFの生成
リクエスト:
{
"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"
}
}
レスポンス- 成功:
{
"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"
}
}
}
レスポンス- 失敗:
{
"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"
}
}
}
詳細は、次を参照してください:
例2: 複数のPDFの生成- インラインで指定されたデータ
リクエスト:
{
"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"
}
}
レスポンス- 成功:
{
"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"
}
}
}
詳細は、次を参照してください:
バッチ出力の文書名
"responseType": "BATCH"
を使用すると、複数のドキュメントが生成されます。これらのドキュメントのネーミングを制御するには、ドキュメント名の必須{documentId}
を使用します。
output.objectName形式 | 説明 | サンプル |
---|---|---|
invoice{documentId}.pdf |
パディングなし。1から始まる。 | invoice1.pdf, invoice2.pdf |
invoice{documentId|zeroPadding=auto}.pdf |
バッチ内のドキュメント数に基づく自動パディング。1から始まる。 | invoice01.pdf ... invoice10.pdf |
invoice{documentId|firstId=51}.pdf |
ゼロ埋込みなし。51から始まる。 | invoice51.pdf, invoice52.pdf |
invoice{documentId|firstId=51,zeroPadding=5}.pdf |
5桁の左パディング(0)51から始まる。 | invoice00051.pdf, invoice00052.pdf |
invoice{documentId|zeroPadding=5}.pdf |
5桁の左パディング(0)1から始まる。 | invoice00001.pdf, invoice00002.pdf |
サポートされているドキュメント・タイプ
テンプレートから(contentType) | 出力(contentType) |
---|---|
Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document ) |
PDF(アプリケーション/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(アプリケーション/PDF) |
Microsoft Excel(2010以上)(application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ) |
Microsoft Excel(2010以上)(application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ) |
フォント
PDFの生成時には、次のフォントを使用できます。
- カラデア
- Cookie
- Carlito
- DejaVu
- LiberationMono (通信事業者)
- LiberationSans (トライアル)
- LiberationSerif (Times New Roman)
- NotoSans- 黒
- NotoSans-BoldItalic
- NotoSans-ExtraLight
- NotoSans- ライト
- NotoSans-MediumItalic
- NotoSans-SemiBoldItalic
- NotoSans-BlackItalic
- NotoSans-ExtraBold
- NotoSans-ExtraLightItalic
- NotoSans-LightItalic
- NotoSans- 通常
- NotoSans- 薄い
- NotoSans- 太字
- NotoSans-ExtraBoldItalic
- NotoSans- 斜体
- NotoSans- 中
- NotoSans-SemiBold
- NotoSans-ThinItalic
- NotoSansJP- 太字
- NotoSansJP- 通常
- NotoSansKR- 通常
- NotoSansKR- 太字
- NotoSansSC- 通常
- NotoSansSC- 太字
- NotoSansTC- 通常
- NotoSansTC-Bold.otf
- NotoSansArabic- 通常
- NotoSansArabic- 太字
- NotoSansHebrew- 通常
- NotoSansHebrew- 太字
- NotoSerif- 太字
- NotoSerif-BoldItalic
- NotoSerif- 斜体
- NotoSerif- 通常
- OracleSans- 太字
- OracleSans- 通常
- オズワルド・ボールド
- オズワルド-ExtraLight
- オズワルドライト
- オズワルド- 中
- オズワルド国民
- オズワルド-SemiBold
このリストにないフォントが必要な場合は、ドキュメント・ジェネレータ・リクエストでフォント・バンドルを指定できます。フォントバンドルは、PDF生成時に使用される .ttfおよび .otfファイルを含むzipファイルです。例については、RequestSingleリファレンスを参照してください
パスワードを使用した生成済PDFドキュメントの保護
1つのPDF ("requestType": "SINGLE"
を使用)または複数のPDF ("requestType": "BATCH"
を使用)を生成する場合は、生成されたPDFを保護するためのパスワードを指定できます。PDFを生成したら、PDFを開く前にパスワードを入力する必要があります。
生成されたPDFを保護するためのパスワードを指定するには、リクエストの"options"
セクションに"documentOpenPassword" : "<a-password>"
を含めます。<a-password>
の値は、長さが1文字から127文字の英数字文字列である必要があります。
例:
{
"requestType": "SINGLE",
"tagSyntax": "DOCGEN_1_0",
"data": ...
"template": ...
"output": ...
"options": {
"documentOpenPassword" : "MyPasswordToOpenTheDocument"
}
}
文書ジェネレータ・テンプレート・タグ
テンプレート・タグの完全なリストは、次を参照してください。
トラブルシューティング
OCI Functions共通ステータス・コード
次の表に、事前構築済ファンクションの操作時に発生する可能性がある一般的なOCIファンクション・エラーの概要を示します。
エラー・コード | Error Message | アクション |
---|---|---|
200 | 完了 | なし |
404 | NotAuthorizedOrNotFound | 必要なポリシーが構成されていることを確認します(FnプロジェクトのCLIコマンドの実行による404エラーの戻りを参照)。 |
444 | タイム・アウト |
ファンクションの実行中にクライアントとOCIファンクション間の接続が中断されました(ファンクションを呼び出すと、クライアントがタイムアウトをレポートし、ファンクションのログに444エラーが表示されますを参照)。再試行すると問題が解決する可能性があります。 ほとんどのクライアントの内部タイムアウトは60秒です。組み込み関数のタイムアウトが300秒に設定されている場合でも、次のことが必要な場合があります。
詳細は、関数の呼出しを参照してください。 |
502, 504 | (各種) | ほとんどの問題では、502ステータス・コードが返されます(「ファンクションの呼出しは、ファンクションの失敗メッセージおよび502エラーを返します」を参照)。「error receiving function response」というメッセージを含む502エラーは、メモリー割り当てを増やすことによって解決される可能性があります。502は、関数が一時的な状態にあるときに発生することがあります。再試行すると問題が解決する可能性があります。 |
原因をさらに特定するには、事前構築済ファンクションのロギング機能を有効にします(ファンクション・ログの格納および表示を参照)。ファンクションのトラブルシューティングの詳細は、OCIファンクションのトラブルシューティングを参照してください。
文書ジェネレータの事前作成機能ステータス・コード
ステータス・コード | 説明 |
---|---|
200 | 完了 |
207 | responseType=BATCHの場合は、個々のドキュメントのレスポンス・コードを確認します。 |
400 | 検証エラーまたは処理エラー。ObjectNotFoundエラーが返された場合は、ファンクションを含むサブネットがオブジェクト・ストレージ・サービスにアクセスできることを確認します。 |
500 | 内部エラー |
原因をさらに特定するには、事前構築済ファンクションのロギング機能を有効にします(ファンクション・ログの格納および表示を参照)。
ログ分析のヒント
すべての組み込み関数は、ロギングレベルを構成パラメータとして指定するオプションを提供します。ロギング・レベルをDEBUG
に設定して、詳細情報を取得できます。
アプリケーションには複数の関数があるため、事前に作成された関数ログエントリは接頭辞「PBF | <PBF NAME>」で識別されます。
たとえば、ドキュメント ジェネレータの組み込み関数のログ エントリは次のようになります。
"PBF | Document Generator | INFO | 2023-08-31T20:19:51.181593Z | 2. LOG001 - Setting Log Level to : DEBUG"