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

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

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

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

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

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

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

بنية أقنعة حقل التحديث هي نفسها صيغة أقنعة حقل القراءة.

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

يستخدم المثال التالي 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"
}