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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

از ابرداده توسعه‌دهنده قابل مشاهده پروژه به عنوان مکانیزم امنیتی یا برای ذخیره اسرار استفاده نکنید. ممکن است فراداده در معرض دید کاربرانی قرار گیرد که به سند دسترسی دارند.

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

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

اگرچه می‌توانید «متاداده» خود را هنگام ایجاد فراداده مشخص کنید، توصیه می‌کنیم به سرویس Sheets اجازه دهید یکی را به شما اختصاص دهد.

ابرداده ایجاد کنید

برای ایجاد ابرداده، از متد 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 منطبق استفاده کنید.

مقادیر سلول را بر اساس فراداده دریافت کنید

برای بدست آوردن مقادیر سلول بر اساس فراداده، از روش 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 برگردانید. باید شناسه صفحه‌گسترده و یک یا چند فیلتر داده که با فراداده مطابقت دارند را مشخص کنید.

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

یک مثال نشان دهید

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

درخواست کنید

{
  "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"
  ]
}

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

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

مورد	تخصیص محدودیت ذخیره سازی
صفحه گسترده	30000 کاراکتر
هر صفحه در یک صفحه گسترده	30000 کاراکتر

می توانید حداکثر 30000 کاراکتر را برای صفحه گسترده ذخیره کنید. علاوه بر این، می توانید 30000 کاراکتر برای هر صفحه در یک صفحه گسترده ذخیره کنید (30000 کاراکتر برای برگه یک، 30000 کاراکتر برای صفحه 2 و غیره). بنابراین یک صفحه گسترده با 3 صفحه می تواند تا 120000 کاراکتر متادیتای توسعه دهنده داشته باشد.

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

این محدودیت ها ممکن است در آینده تغییر کند.