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

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

フィールド マスクを使用して読み取る

ドキュメントは大きくなることがあり、読み取りリクエストで返される Document リソースのすべての部分が必要になることはほとんどありません。fields URL パラメータを使用すると、ドキュメント API のレスポンスで返される内容を制限できます。最適なパフォーマンスを得るには、返信で必要なフィールドのみを明示的にリストします。

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
        },
      }
    }
  ],
}