フィールド マスクを使用すると、API 呼び出し元は、リクエストで返または更新する必要があるフィールドをリストできます。FieldMask を使用すると、API で不要な処理を回避でき、パフォーマンスが向上します。フィールド マスクは、Google ドキュメント API の読み取りメソッドと更新メソッドの両方で使用されます。
フィールド マスクを使用した読み取り
ドキュメントはサイズが大きくなる場合があり、多くの場合、読み取りリクエストで返される Document リソースのすべての部分は必要ありません。fields URL パラメータを使用すると、Docs API レスポンスで返される内容を制限できます。最適なパフォーマンスを得るには、応答で必要なフィールドのみを明示的に列挙します。
fields パラメータの形式は FieldMask の JSON エンコードと同じです。簡単に言うと、複数の異なるフィールドはカンマ区切りで、サブフィールドはドットで区切ります。フィールド名は、camelCaseまたはcamelCase形式で指定できます。便宜上、同じタイプの複数のサブフィールドはかっこ内にリストできます。
次の documents.get リクエストの例では、title,body.content(paragraph),revisionId のフィールド マスクを使用して、ドキュメントの title、Body オブジェクトの Paragraph、ドキュメント内のドキュメントの revisionId を取得します。
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
このメソッド呼び出しに対するレスポンスは、フィールド マスクでリクエストされたコンポーネントを含む Document オブジェクトです。
{
"title": ""TITLE",
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": ""CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
"revisionId": "REVISION_ID"
}
フィールド マスクを使用して更新する
オブジェクト内の特定のフィールドのみを更新し、他のフィールドは変更しない必要がある場合があります。documents.batchUpdate オペレーション内の更新リクエストでは、フィールド マスクを使用して、変更対象のフィールドを API に伝えます。更新リクエストでは、フィールド マスクで指定されていないフィールドは無視され、現在の値が使用されます。
更新されたメッセージでフィールドを指定せず、そのフィールドをマスクに追加して、フィールドの設定を解除することもできます。これにより、それまで設定されていた値が消去されます。
更新フィールド マスクの構文は、読み取りフィールド マスクと同じです。
次の例では、UpdateTextStyleRequest を使用して、ドキュメント内の「Google Docs API」という単語を、range 5 ～ 20 内で太字にスタイル設定しています。
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"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
},
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID"
}