استخدام أقنعة الحقول

وتعدّ أقنعة الحقول طريقة لمُطلِبي البيانات من واجهة برمجة التطبيقات لتصنيف الحقول التي يجب أن يعرضها الطلب أو يعدّلها. يتيح استخدام ملف برمجي FieldMask لواجهة برمجة التطبيقات تجنُّب العمل غير الضروري وتحسين الأداء. يتم استخدام قناع حقل لكل من طريقتَي القراءة والتحديث في Google Docs API.

القراءة باستخدام قناع الحقل

يمكن أن تكون المستندات كبيرة، وغالبًا ما لا تحتاج إلى كل جزء من موارد Document التي يعرضها طلب القراءة. يمكنك تحديد ما يتم عرضه في استجابة واجهة برمجة التطبيقات لمستندات Google باستخدام معلَمة عنوان URL fields. للحصول على أفضل أداء، أدرِج بوضوح الحقول التي تحتاج إليها فقط في الردّ.

يكون تنسيق مَعلمة الحقول هو نفسه ترميز JSON لحقل FieldMask. بعبارة موجزة، يتم فصل الحقول المختلفة المتعددة بفواصل، ويتم فصل الحقول الفرعية بنقاط. يمكن تحديد أسماء الحقول في camelCase أو Separate_by_underscores. لتسهيل الأمر، يمكن إدراج حقول فرعية متعددة من النوع نفسه بين قوسين.

يستخدم مثال طلب documents.get التالي قناع الحقل title,tabs(documentTab(body.content(paragraph))),revisionId لجلب title الخاص بالمستند، وParagraph لكائن Body (من جميع علامات التبويب) و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 أقنعة الحقول لإعلام واجهة برمجة التطبيقات بالحقول التي يتم تغييرها. يتجاهل طلب التعدُّل أي حقول لم يتم تحديدها في قناع الحقول، ويتركها مع قيمها الحالية.

يمكنك أيضًا إلغاء ضبط حقل من خلال عدم تحديده في الرسالة المعدّلة، ولكن بإضافة الحقل إلى القناع. هذا يمحو أي قيمة كان يمتلكها الحقل سابقًا.

تكون بنية أقنعة حقول التعديل مماثلة لبنية أقنعة حقول القراءة.

يُعامل قناع الحقل * كعنصر نائب وهو اختصار لتحديد كل حقل في رسالة. يمكن أن تؤدي بنية العنصر النائب إلى ظهور نتائج غير مرغوب فيها في حال تم تحديث واجهة برمجة التطبيقات في المستقبل، لأنّ الحقول التي يمكن قراءتها فقط والحقول التي تمت إضافتها حديثًا قد تؤدي إلى حدوث أخطاء. بالنسبة إلى التطبيقات العلنية، احرص دائمًا على إدراج الحقول المحدّدة التي يتم تعديلها في أقنعة الحقول وتجنَّب استخدام * العناصر النائبة.

يستخدم المثال التالي الرمز 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
        },
      }
    }
  ],
}