خواندن & ابرداده توسعه دهنده بنویسید

ویژگی فراداده توسعه‌دهنده به شما امکان می‌دهد فراداده را با موجودیت‌ها و مکان‌های مختلف در یک صفحه گسترده مرتبط کنید. سپس می‌توانید از این فراداده پرس‌وجو کنید و از آن برای یافتن اشیاء مرتبط با آن استفاده کنید.

شما می‌توانید متادیتا را با ردیف‌ها، ستون‌ها، برگه‌ها یا یک صفحه گسترده مرتبط کنید.

فراداده‌های توسعه‌دهنده به شما امکان می‌دهد عملیاتی مانند موارد زیر را انجام دهید:

  • داده‌های دلخواه را با موجودیت‌ها و مکان‌های مختلف در یک صفحه گسترده مرتبط کنید — برای مثال، totals با ستون D یا responseId = 1234 با ردیف 7 مرتبط کنید.

  • یافتن تمام مکان‌ها و داده‌های مرتبط با یک کلید یا ویژگی فراداده خاص — برای مثال، با توجه به totals کلیدهای مرتبط با ستون D یا با توجه به responseId ، تمام ردیف‌ها را با فراداده responseId و مقدار فراداده مرتبط با آنها برمی‌گرداند.

  • یافتن تمام داده‌های مرتبط با یک موجودیت یا مکان خاص — برای مثال، با توجه به ستون D، تمام فراداده‌های مرتبط با آن مکان را برمی‌گرداند.

  • بازیابی مقادیر در یک مکان با مشخص کردن فراداده‌های مرتبط — برای مثال، با توجه به totals ، نمایشی از مقادیر موجود در ستون یا ردیف مرتبط را برمی‌گرداند یا با توجه به summary نمایشی از منبع Sheet مرتبط را برمی‌گرداند.

  • به‌روزرسانی مقادیر در یک مکان با مشخص کردن فراداده‌های مرتبط — برای مثال، به جای به‌روزرسانی مقادیر در یک ردیف از طریق نمادگذاری A1 ، مقادیر را با مشخص کردن شناسه فراداده به‌روزرسانی کنید.

خواندن و نوشتن متادیتا

منبع spreadsheets.developerMetadata دسترسی به فراداده‌های توسعه‌دهنده مرتبط با یک مکان یا شیء در یک صفحه گسترده را فراهم می‌کند.

درباره فراداده توسعه‌دهنده

این بخش برخی از جنبه‌های کلیدی فراداده‌های توسعه‌دهنده را که باید هنگام کار با Sheets API در نظر بگیرید، شرح می‌دهد.

فراداده به عنوان برچسب

یکی از کاربردهای فراداده توسعه‌دهنده، تگی است که مکانی را در صفحه گسترده تنها با استفاده از یک کلید و یک مکان نامگذاری می‌کند. برای مثال، می‌توانید headerRow با یک ردیف خاص یا totals با یک ستون خاص در یک صفحه مرتبط کنید. تگ‌ها می‌توانند برای اتصال معنایی بخش‌هایی از یک صفحه گسترده به فیلدهای یک ابزار یا پایگاه داده شخص ثالث استفاده شوند، بنابراین تغییرات در صفحه گسترده، برنامه شما را خراب نمی‌کند.

فراداده به عنوان ویژگی‌ها

متادیتای ایجاد شده با مشخص کردن یک کلید، مکان و یک مقدار ، به عنوان یک جفت کلید-مقدار مرتبط با آن مکان در یک برگه عمل می‌کند. به عنوان مثال، می‌توانید موارد زیر را مرتبط کنید:

  • formResponseId = resp123 با یک ردیف
  • lastUpdated = 1477369882 با یک ستون.

این به شما امکان می‌دهد ویژگی‌های دارای نام سفارشی مرتبط با نواحی یا داده‌های خاص را در یک صفحه گسترده ذخیره و به آنها دسترسی داشته باشید.

فراداده قابل مشاهده پروژه در مقابل سند

برای جلوگیری از تداخل یک پروژه توسعه‌دهنده با فراداده‌های پروژه دیگر، دو تنظیم visibility فراداده وجود دارد: project و document . با استفاده از Sheets API، فراداده‌های پروژه فقط از پروژه توسعه‌دهنده‌ای که آن را ایجاد کرده است قابل مشاهده و دسترسی هستند. فراداده‌های سند از هر پروژه توسعه‌دهنده‌ای که به سند دسترسی دارد، قابل دسترسی هستند.

پرس‌وجوهایی که صراحتاً قابلیت مشاهده را مشخص نمی‌کنند، فراداده‌های سند منطبق و فراداده‌های پروژه منطبق را برای پروژه توسعه‌دهنده‌ای که درخواست را انجام می‌دهد، برمی‌گردانند.

منحصر به فرد بودن

کلیدهای متادیتا لازم نیست منحصر به فرد باشند، اما metadataId باید متمایز باشد. اگر متادیتا ایجاد کنید و فیلد شناسه آن را مشخص نکنید، API یکی را اختصاص می‌دهد. این شناسه می‌تواند برای شناسایی متادیتا استفاده شود، در حالی که کلیدها و سایر ویژگی‌ها می‌توانند برای شناسایی مجموعه‌های متادیتا استفاده شوند.

ایجاد فراداده

برای ایجاد فراداده، از متد batchUpdate استفاده کنید و یک createDeveloperMetadataRequest با metadataKey ، location و visibility ارائه دهید. می‌توانید به صورت اختیاری یک metadataValue یا یک metadataId صریح مشخص کنید.

اگر شناسه‌ای را مشخص کنید که از قبل استفاده می‌شود، درخواست ناموفق خواهد بود. اگر شناسه‌ای ارائه ندهید، API یکی را اختصاص می‌دهد.

در این مثال، ما یک کلید، مقدار و یک ردیف در درخواست ارائه می‌دهیم. پاسخ، این مقادیر فراداده توسعه‌دهنده را به همراه شناسه فراداده اختصاص داده شده، برمی‌گرداند.

درخواست

{
  "requests": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "location": {
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT",
          "metadataKey": "Sales",
          "metadataValue": "2022"
        }
      }
    }
  ]
}

پاسخ

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "metadataId": metadataId,
          "metadataKey": "Sales",
          "metadataValue": "2022",
          "location": {
            "locationType": "ROW",
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT"
        }
      }
    }
  ]
}

خواندن یک آیتم فراداده واحد

برای بازیابی یک فراداده‌ی توسعه‌دهنده‌ی واحد و مجزا، از متد spreadsheets.developerMetadata.get استفاده کنید و spreadsheetId حاوی فراداده و metadataId منحصر به فرد توسعه‌دهنده‌ی فراداده را مشخص کنید.

درخواست

در این مثال، ما شناسه صفحه گسترده و شناسه فراداده را در درخواست ارائه می‌دهیم. پاسخ، مقادیر فراداده توسعه‌دهنده را برای شناسه فراداده برمی‌گرداند.

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId

پاسخ

{
  "metadataId": metadataId,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": sheetId,
      "dimension": "ROWS",
      "startIndex": 6,
      "endIndex": 7
    }
  },
  "visibility": "DOCUMENT"
}

خواندن چندین آیتم فراداده

برای بازیابی چندین مورد از فراداده‌های توسعه‌دهنده، از متد spreadsheets.developerMetadata.search استفاده کنید. باید یک DataFilter مشخص کنید که با هر فراداده موجود در هر ترکیبی از ویژگی‌ها مانند کلید، مقدار، مکان یا قابلیت مشاهده مطابقت داشته باشد.

در این مثال، ما چندین شناسه فراداده را در درخواست ارائه می‌دهیم. پاسخ، مقادیر فراداده توسعه‌دهنده را برای هر شناسه فراداده برمی‌گرداند.

درخواست

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    },
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

پاسخ

{
  "matchedDeveloperMetadata": [
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Revenue",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    },
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Sales",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

به‌روزرسانی فراداده

برای به‌روزرسانی متادیتای توسعه‌دهنده، از متد spreadsheets.batchUpdate استفاده کنید و یک UpdateDeveloperMetadataRequest ارائه دهید. شما باید یک DataFilter که متادیتای به‌روزرسانی‌شده را هدف قرار می‌دهد، یک شیء DeveloperMetadata با مقادیر جدید و یک ماسک فیلد که فیلدهای به‌روزرسانی‌شده را توصیف می‌کند، مشخص کنید.

در این مثال، ما شناسه فراداده، شناسه برگه و یک کلید فراداده جدید را در درخواست ارائه می‌دهیم. پاسخ، این مقادیر فراداده توسعه‌دهنده را به همراه کلید فراداده به‌روزرسانی‌شده برمی‌گرداند.

درخواست

{
  "requests": [
    {
      "updateDeveloperMetadata": {
        "dataFilters": [
          {
            "developerMetadataLookup": {
              "metadataId": metadataId
            }
          }
        ],
        "developerMetadata": {
          "location": {
            "sheetId": sheetId
          },
          "metadataKey": "SalesUpdated"
        },
        "fields": "location,metadataKey"
      }
    }
  ]
}

پاسخ

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

حذف فراداده

برای حذف متادیتای توسعه‌دهنده، از متد batchUpdate استفاده کنید و یک DeleteDeveloperMetadataRequest ارائه دهید. برای انتخاب متادیتایی که می‌خواهید حذف کنید، باید یک DataFilter مشخص کنید.

در این مثال، ما شناسه فراداده را در درخواست ارائه می‌دهیم. پاسخ، مقادیر فراداده توسعه‌دهنده را برای شناسه فراداده برمی‌گرداند.

برای تأیید حذف متادیتای توسعه‌دهنده، از متد spreadsheets.developerMetadata.get استفاده کنید و شناسه متادیتای حذف‌شده را مشخص کنید. باید یک پاسخ کد وضعیت HTTP با کد 404: Not Found دریافت کنید، به همراه پیامی با عنوان «متادیتای توسعه‌دهنده با شناسه metadataId وجود ندارد».

درخواست

{
  "requests": [
    {
      "deleteDeveloperMetadata": {
        "dataFilter": {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      }
    }
  ]
}

پاسخ 

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

خواندن و نوشتن مقادیر مرتبط با فراداده

همچنین می‌توانید با مشخص کردن متادیتای توسعه‌دهنده‌ی مرتبط و مقادیری که می‌خواهید به‌روزرسانی کنید، مقادیر سلول‌ها را در ردیف‌ها و ستون‌ها بازیابی و به‌روزرسانی کنید. برای انجام این کار، از روش مناسب زیر به همراه یک DataFilter منطبق استفاده کنید.

دریافت مقادیر سلول‌ها بر اساس فراداده (metadata)

برای دریافت مقادیر سلول‌ها بر اساس فراداده، از متد spreadsheets.values.batchGetByDataFilter استفاده کنید. باید شناسه صفحه گسترده و یک یا چند فیلتر داده که با فراداده مطابقت دارند را مشخص کنید.

در این مثال، ما شناسه فراداده را در درخواست ارائه می‌دهیم. پاسخ، مقادیر سلول‌های ردیف (شماره مدل، فروش ماهانه) را برای شناسه فراداده برمی‌گرداند.

درخواست 

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "majorDimension": "ROWS"
}

پاسخ 

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

دریافت صفحه گسترده بر اساس فراداده

هنگام بازیابی یک صفحه گسترده، می‌توانید زیرمجموعه‌ای از داده‌ها را با استفاده از متد spreadsheets.getByDataFilter برگردانید. باید شناسه صفحه گسترده و یک یا چند فیلتر داده که با فراداده مطابقت دارند را مشخص کنید.

این درخواست مانند یک درخواست معمولی "spreadsheet GET" عمل می‌کند، با این تفاوت که لیست متادیتاهای منطبق با فیلترهای داده مشخص شده، تعیین می‌کند که کدام برگه‌ها، داده‌های شبکه و سایر منابع شیء دارای متادیتا بازگردانده شوند. اگر includeGridData روی true تنظیم شده باشد، داده‌های شبکه‌ای که محدوده‌های شبکه مشخص شده را قطع می‌کنند نیز برای برگه بازگردانده می‌شوند.

در این مثال، ما شناسه‌ی متادیتا را ارائه می‌دهیم و includeGridData را در درخواست روی false تنظیم می‌کنیم. پاسخ، هر دو ویژگی spreadsheet و sheet را برمی‌گرداند.

درخواست 

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "includeGridData": false
}

پاسخ 

{
  "spreadsheetId": spreadsheetId,
  "properties": {
    "title": "Sales Sheet",
    "locale": "en_US",
    "autoRecalc": "ON_CHANGE",
    "timeZone": "America/Los_Angeles",
    "defaultFormat": {
      "backgroundColor": {
        "red": 1,
        "green": 1,
        "blue": 1
      },
      "padding": {
        "top": 2,
        "right": 3,
        "bottom": 2,
        "left": 3
      },
      "verticalAlignment": "BOTTOM",
      "wrapStrategy": "OVERFLOW_CELL",
      "textFormat": {
        "foregroundColor": {},
        "fontFamily": "arial,sans,sans-serif",
        "fontSize": 10,
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "foregroundColorStyle": {
          "rgbColor": {}
        }
      },
      "backgroundColorStyle": {
        "rgbColor": {
          "red": 1,
          "green": 1,
          "blue": 1
        }
      }
    },
    "spreadsheetTheme": {
      "primaryFontFamily": "Arial",
      "themeColors": [
        {
          "colorType": "TEXT",
          "color": {
            "rgbColor": {}
          }
        },
        {
          "colorType": "BACKGROUND",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 1,
              "blue": 1
            }
          }
        },
        {
          "colorType": "ACCENT1",
          "color": {
            "rgbColor": {
              "red": 0.25882354,
              "green": 0.52156866,
              "blue": 0.95686275
            }
          }
        },
        {
          "colorType": "ACCENT2",
          "color": {
            "rgbColor": {
              "red": 0.91764706,
              "green": 0.2627451,
              "blue": 0.20784314
            }
          }
        },
        {
          "colorType": "ACCENT3",
          "color": {
            "rgbColor": {
              "red": 0.9843137,
              "green": 0.7372549,
              "blue": 0.015686275
            }
          }
        },
        {
          "colorType": "ACCENT4",
          "color": {
            "rgbColor": {
              "red": 0.20392157,
              "green": 0.65882355,
              "blue": 0.3254902
            }
          }
        },
        {
          "colorType": "ACCENT5",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 0.42745098,
              "blue": 0.003921569
            }
          }
        },
        {
          "colorType": "ACCENT6",
          "color": {
            "rgbColor": {
              "red": 0.27450982,
              "green": 0.7411765,
              "blue": 0.7764706
            }
          }
        },
        {
          "colorType": "LINK",
          "color": {
            "rgbColor": {
              "red": 0.06666667,
              "green": 0.33333334,
              "blue": 0.8
            }
          }
        }
      ]
    }
  },
  "sheets": [
    {
      "properties": {
        "sheetId": sheetId,
        "title": "Sheet7",
        "index": 7,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 26
        }
      }
    }
  ],
  "spreadsheetUrl": spreadsheetUrl
}

به‌روزرسانی مقادیر بر اساس فراداده

برای به‌روزرسانی مقادیر سلول که با فراداده‌های خاص مطابقت دارند، از متد spreadsheets.values.batchUpdateByDataFilter استفاده کنید. باید شناسه صفحه گسترده، valueInputOption و یک یا چند DataFilterValueRange که با فراداده‌ها مطابقت دارند را مشخص کنید.

در این مثال، ما شناسه فراداده و مقادیر ردیف به‌روزرسانی‌شده را در درخواست ارائه می‌دهیم. پاسخ، هم ویژگی‌ها و هم داده‌های به‌روزرسانی‌شده را برای شناسه فراداده برمی‌گرداند.

درخواست 

{
  "data": [
    {
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

پاسخ 

{
  "spreadsheetId": spreadsheetId,
  "totalUpdatedRows": 1,
  "totalUpdatedColumns": 2,
  "totalUpdatedCells": 2,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "updatedRange": "Sheet7!A7:B7",
      "updatedRows": 1,
      "updatedColumns": 2,
      "updatedCells": 2,
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "updatedData": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "84"
          ]
        ]
      }
    }
  ]
}

پاک کردن مقادیر بر اساس فراداده

برای پاک کردن مقادیر سلولی که با فراداده‌های خاص مطابقت دارند، از متد spreadsheets.values.batchClearByDataFilter استفاده کنید. برای انتخاب فراداده‌ای که می‌خواهید پاک کنید، باید یک فیلتر داده مشخص کنید.

درخواست

در این مثال، ما شناسه فراداده را در درخواست ارائه می‌دهیم. پاسخ، شناسه صفحه گسترده و محدوده‌های پاک‌شده را برمی‌گرداند. 

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

پاسخ 

{
  "spreadsheetId": spreadsheetId,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

محدودیت‌های ذخیره‌سازی فراداده

محدودیتی در کل مقدار فراداده‌ای که می‌توانید در یک صفحه گسترده ذخیره کنید وجود دارد. این محدودیت بر حسب کاراکتر اندازه‌گیری می‌شود و از دو جزء تشکیل شده است:

مورد تخصیص محدودیت ذخیره‌سازی
صفحه گسترده ۳۰،۰۰۰ کاراکتر
هر برگه در یک صفحه گسترده ۳۰،۰۰۰ کاراکتر

شما می‌توانید تا ۳۰۰۰۰ کاراکتر برای صفحه گسترده ذخیره کنید. علاوه بر این، می‌توانید برای هر برگه در یک صفحه گسترده ۳۰۰۰۰ کاراکتر ذخیره کنید (۳۰۰۰۰ برای برگه اول، ۳۰۰۰۰ برای برگه دوم و به همین ترتیب). بنابراین یک صفحه گسترده با ۳ صفحه می‌تواند تا ۱۲۰۰۰۰ کاراکتر از فراداده‌های توسعه‌دهنده را در خود جای دهد.

هر کاراکتر در ویژگی‌های کلید و مقدار یک شیء developerMetadata در این محدودیت محاسبه می‌شود.