Oracle Cloud Infrastructureドキュメント

ドキュメント・ジェネレータ関数

OCI FunctionsのDocument Generator組み込み関数を使用して、OfficeテンプレートとJSONデータに基づいてドキュメントを生成する方法をご覧ください。

一般的な使用方法のシナリオ

文書ジェネレータ機能の一般的な使用方法は次のとおりです。

  • OfficeテンプレートおよびJSONデータをオブジェクト・ストレージに配置し、関数を直接起動してPDFドキュメントを生成し、結果をオブジェクト・ストレージに格納します。

文書ジェネレータ機能に関連するサービスは次のとおりです。

前提条件と推奨事項

この事前作成機能を使用する場合のベスト・プラクティスを次に示します。

  • アプリケーションにリンクされたVCNが、サービス・ゲートウェイ、インターネット・ゲートウェイまたはNATゲートウェイを使用して、他のOCIサービスへのアクセスを容易にします。
  • ほとんどのタスクでデフォルトのメモリー・サイズを512MBに設定します。大きいデータ・セットを使用したり、フォントをバンドルしたり、バッチ処理を使用したりすると、より多くのメモリーが必要になる場合があります。
  • バッチ処理の場合は、事前に作成された関数のタイムアウトを300秒に設定します。

文書ジェネレータ機能の構成

文書ジェネレータ機能を構成するには、次のステップを実行します。

  1. 「事前作成関数」ページで、「ドキュメント・ジェネレータ」、「ファンクションの作成」の順に選択します。
  2. 次のようにして、「名前」、「コンパートメント」および「アプリケーション」を構成します:
    • 名前:新しいファンクションの名前。名前は、文字またはアンダースコアで始まり、文字、数字、ハイフンまたはアンダースコアが続く必要があります。長さは1から255文字です。機密情報の入力は避けてください。

      別のコンパートメントにファンクションを作成するには、「コンパートメントの変更」を選択します。

    • アプリケーション:関数を作成するアプリケーションを選択します。

      適切なアプリケーションが現在のコンパートメントにまだ存在しない場合は、「新規アプリケーションの作成」を選択し、次の詳細を指定します:

      • 名前:新しいアプリケーションの名前。機密情報の入力は避けてください。
      • VCN:アプリケーションでファンクションを実行するVCN (仮想クラウド・ネットワーク)。オプションで、「VCNコンパートメント: 」を選択して、別のコンパートメントからVCNを選択します。
      • サブネット:ファンクションを実行するサブネット(最大3つ)です。オプションで、「サブネット・コンパートメント: 」を選択して、別のコンパートメントからサブネットを選択します。
      • シェイプ:アプリケーションでファンクションをデプロイおよび実行するコンピュート・インスタンスのプロセッサ・アーキテクチャ。アプリケーション内のすべてのファンクションは、同じアーキテクチャのコンピュート・インスタンスにデプロイされ、実行されます。ファンクションのイメージには、選択するアーキテクチャに必要な依存関係が含まれている必要があります。
      • タグ: リソースを作成する権限がある場合、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済タグを適用するには、タグ・ネームスペースを使用する許可が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかがわからない場合は、このオプションをスキップするか、管理者に問い合せてください。後でタグを適用できます。
  3. 事前構築済ファンクションのIAMポリシーを構成します。

    デフォルトでは、OCI Functionsは、事前構築済ファンクションの実行に必要なポリシー・ステートメントを使用して、動的グループおよびIAMポリシーを作成します。次の手順を実行します。

    • OCI Functionsで動的グループおよびポリシーを自動的に作成する場合は、デフォルトの動作を受け入れる変更を行いません。
    • OCI Functionsで動的グループとポリシーを自動的に作成しない場合は、「動的グループとIAMポリシーを作成しないでください」を選択します。
    重要

    「動的グループとIAMポリシーを作成しない」オプションを選択した場合は、動的グループとIAMポリシーを自分で定義する必要があります。詳細は、権限を参照してください。
  4. 関数メモリーおよびタイムアウト値を次のように構成します。
    • メモリー(MB):ファンクションが実行中に使用できるメモリーの最大量(MB)。これはファンクション・イメージで使用可能なメモリーです。(デフォルト: 512 MB)
    • タイムアウト(秒):ファンクションを実行できる最大時間(秒)。指定された時間内に関数が完了しない場合は、その関数が取り消されます。(デフォルト: 300)
  5. (オプション)プロビジョニングされた同時実行性を構成して、実行インフラストラクチャを常に使用可能にする同時ファンクション呼出しの最小数を指定することで、ファンクションの起動時の初期遅延を最小限に抑えます。(デフォルト: 未選択)

    選択した場合、このファンクションに割り当てられるプロビジョニングされた同時実行ユニットの数を指定します。デフォルト: 10

    プロビジョニングされた同時実行性の詳細は、プロビジョニングされた同時実行性を使用した初期レイテンシの削減を参照してください。

  6. 構成オプションの説明に従い、ファンクション構成パラメータを設定します。
  7. オプションで、「タグ」セクションに任意のタグを入力します。リソースを作成する権限を持つ場合、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済タグを適用するには、タグ・ネームスペースを使用する許可が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかがわからない場合は、このオプションをスキップするか、管理者に問い合せてください。タグは後で適用できます。
  8. 「作成」を選択します。

デプロイ・ダイアログに、ファンクションをデプロイするタスクが表示されます(「事前構築済ファンクション・デプロイメントの終了」を参照)。

構成オプション

構成パラメータ

名前 説明 必須
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秒に設定されている場合でも、次のことが必要な場合があります。

  • OCI CLIを使用する場合: --read-timeout 300を使用します
  • OCI SDKを使用する場合: クライアントの作成時に読取りタイムアウトを300に設定します
  • DBMS_CLOUD.SEND_REQUESTを使用する場合: UTL_HTTP.set_transfer_timeout(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"