フィールド マスクを使用する

フィールド マスクは、API 呼び出し元がリクエストで返すまたは更新するフィールドを一覧表示する方法です。FieldMask を使用すると、API で不要な処理を回避し、パフォーマンスを向上させることができます。フィールド マスクは、Google Docs API の読み取りメソッドと更新メソッドの両方に使用されます。

フィールド マスクを使用した読み取り

ドキュメントはサイズが大きい場合があり、読み取りリクエストによって返される Document リソースのすべての部分が必要ない場合もあります。Docs API レスポンスで返される内容は、fields URL パラメータを使用して制限できます。パフォーマンスを最適にするには、レスポンスで必要なフィールドのみを明示的にリストします。

fields パラメータの形式は、FieldMask の JSON エンコードと同じです。簡単に説明すると、複数のフィールドはカンマで区切り、サブフィールドはドットで区切ります。フィールド名は camelCase または separated_by_underscores で指定できます。便宜上、同じタイプの複数のサブフィールドを括弧内に指定できます。

次の documents.get リクエストの例では、title,tabs(documentTab(body.content(paragraph))),revisionId のフィールド マスクを使用して、ドキュメントの title、Body オブジェクトの Paragraph（すべてのタブから）、ドキュメント内のドキュメントの revisionId を取得します。

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId

このメソッド呼び出しのレスポンスは、フィールドマスクでリクエストされたコンポーネントを含む Document オブジェクトです。

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {},
            {
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

フィールド マスクを使用して更新する

オブジェクト内の特定のフィールドのみを更新し、他のフィールドは変更しないことが必要な場合があります。documents.batchUpdate オペレーション内の更新リクエストでは、フィールド マスクを使用して、変更対象のフィールドを API に指定します。更新リクエストは、フィールド マスクで指定されていないフィールドを無視し、現在の値をそのまま使用します。

更新されたメッセージでフィールドを指定せずに、フィールドをマスクに追加することで、フィールドの設定を解除することもできます。これにより、フィールドに以前設定されていた値がすべて消去されます。

更新フィールド マスクの構文は、読み取りフィールド マスクと同じです。

次の例では、UpdateTextStyleRequest を使用して、ドキュメント内の「Google Docs API」という単語のスタイルを、range 5 ～ 20 で太字にします。

POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
 
{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {
              "endIndex": 1,
              "sectionBreak": {
                "sectionStyle": {
                  "columnSeparatorStyle": "NONE",
                  "contentDirection": "LEFT_TO_RIGHT",
                  "sectionType": "CONTINUOUS"
                }
              }
            },
            {
              "startIndex": 1,
              "endIndex": 59,
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 5,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  },
                  {
                    "startIndex": 5,
                    "endIndex": 20,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {
                        "bold": true
                      }
                    }
                  },
                  {
                    "startIndex": 20,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        },
        {
          ... // style details
        },
      }
    }
  ],
}