このページは Cloud Translation API によって翻訳されました。

テキストをドキュメントに結合する

Google Docs API の便利な用途の 1 つは、1 つ以上のデータソースからの情報をドキュメントに統合することです。

このページでは、外部ソースからデータを取得して、既存のテンプレートドキュメントに挿入する方法について説明します。

テンプレートは特殊なタイプのドキュメントで、テンプレートから作成されるすべてのドキュメントに対して同じ固定テキストのほか、他の動的テキストを配置できる指定のプレースホルダも含みます。たとえば、契約書のテンプレートに、受取人の名前、住所、その他の詳細情報を表示するスポットとともに、固定コンテンツを含めます。アプリは、顧客固有のデータをテンプレートに統合して、完成したドキュメントを作成できます。

このアプローチが有用である理由はいくつかあります。

Google ドキュメントエディタを使用すると、デザイナーは簡単にドキュメントのデザインを調整できます。これは、アプリのパラメータをチューニングしてレンダリングされたレイアウトを設定するよりもはるかに簡単です。
コンテンツをプレゼンテーションから分離することは、よく知られている設計原則であり、多くのメリットがあります。

統合の概念図。

基本的なレシピ

次に、Document API を使用してデータを 1 つのドキュメントに結合する方法の例を示します。

プレースホルダのコンテンツを使用してドキュメントを作成すると、デザインと形式に役立ちます。置き換え対象のテキストの書式は保持されます。
挿入する要素ごとに、プレースホルダのコンテンツをタグに置き換えます。通常は使用されない文字列を使用してください。たとえば、{{account-holder-name}} は適切なタグです。
コード内で、Google Drive API を使用してドキュメントのコピーを作成します。
コードで、Document API の batchUpdate() メソッドを使ってドキュメント名を指定し、ReplaceAllTextRequest を含めます。

ドキュメント ID はドキュメントを参照しており、URL から導出できます。

https://docs.google.com/document/d/documentId/edit

例

次の例では、テンプレート内の 2 つのフィールドを実際の値に置き換えて、完成したドキュメントを生成します。

この統合を行うには、以下のコードを使用します。

Java

        String customerName = "Alice";
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
        String date = formatter.format(LocalDate.now());

        List<Request> requests = new ArrayList<>();
        requests.add(new Request()
                .setReplaceAllText(new ReplaceAllTextRequest()
                        .setContainsText(new SubstringMatchCriteria()
                                .setText("{{customer-name}}")
                                .setMatchCase(true))
                        .setReplaceText(customerName)));
        requests.add(new Request()
                .setReplaceAllText(new ReplaceAllTextRequest()
                        .setContainsText(new SubstringMatchCriteria()
                                .setText("{{date}}")
                                .setMatchCase(true))
                        .setReplaceText(date)));

        BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
        service.documents().batchUpdate(documentId, body.setRequests(requests)).execute();

Node.js

  let customerName = 'Alice';
  let date = yyyymmdd()
  let requests = [
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
      },
    },
    {
      replaceAllText: {
        containsText: {
          text: '{{date}}',
          matchCase: true,
        },
        replaceText: date,
      },
    },
  ];

  google.options({auth: auth});
  google
      .discoverAPI(
          'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')
      .then(function(docs) {
        docs.documents.batchUpdate(
            {
              documentId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
              resource: {
                requests,
              },
            },
            (err, {data}) => {
              if (err) return console.log('The API returned an error: ' + err);
              console.log(data);
            });
      });

Python

    customer_name = 'Alice'
    date = datetime.datetime.now().strftime("%y/%m/%d")

    requests = [
         {
            'replaceAllText': {
                'containsText': {
                    'text': '{{customer-name}}',
                    'matchCase':  'true'
                },
                'replaceText': customer_name,
            }}, {
            'replaceAllText': {
                'containsText': {
                    'text': '{{date}}',
                    'matchCase':  'true'
                },
                'replaceText': str(date),
            }
        }
    ]

    result = service.documents().batchUpdate(
        documentId=document_id, body={'requests': requests}).execute()

テンプレートを管理する

アプリケーションで定義して所有するテンプレートドキュメントの場合は、アプリケーションを表す専用のアカウントを使用してテンプレートを作成します。共有を制限する Google Workspace ポリシーの複雑さを回避できるサービスアカウントをおすすめします。

テンプレートからドキュメントのインスタンスを作成する場合は、必ずエンドユーザーの認証情報を使用します。これにより、ユーザーは作成されるドキュメントを完全に制御でき、ドライブでのユーザーごとの制限に関連するスケーリングの問題を回避できます。

サービスアカウントを使用してテンプレートを作成するには、アプリケーションの認証情報を使用して次の操作を行います。

Docs API の documents.create を使用して、ドキュメントを作成します。
Drive API の permissions.create を使用して権限を更新し、ドキュメントの受信者がドキュメントを閲覧できるようにします。
Drive API の permissions.create を使用して権限を更新し、テンプレート作成者による書き込みを許可します。
必要に応じてテンプレートを編集します。

ドキュメントのインスタンスを作成するには、ユーザー認証情報を使用して次の操作を行います。

Drive API の files.copy を使用してテンプレートのコピーを作成します。
値を置換するには、Documents API の documents.batchUpdate を使用します。