La fonctionnalité de métadonnées pour les développeurs vous permet d'associer des métadonnées à différentes entités et emplacements dans une feuille de calcul. Vous pouvez ensuite interroger ces métadonnées et les utiliser pour rechercher les objets auxquels elles sont associées.
Vous pouvez associer des métadonnées à des lignes, des colonnes, des feuilles ou une feuille de calcul.
Les métadonnées de développement vous permettent d'effectuer des opérations telles que:
Associez des données arbitraires à différentes entités et emplacements dans une feuille de calcul : par exemple, associez
totalsà la colonne D ouresponseId = 1234à la ligne 7.Recherchez tous les emplacements et toutes les données associés à une clé ou à un attribut de métadonnées particulier : par exemple, en fonction de la clé
totalsassociée à la colonne D ou deresponseId, renvoyez toutes les lignes avec les métadonnéesresponseIdet la valeur de métadonnées qui leur sont associées.Rechercher toutes les données associées à une entité ou à un emplacement particulier : par exemple, pour une colonne D donnée, vous obtenez toutes les métadonnées associées à cet emplacement.
Récupérer les valeurs d'un emplacement en spécifiant les métadonnées associées : par exemple, si
totalsrenvoie une représentation des valeurs contenues dans la colonne ou la ligne associée, ou avec unsummaryrenvoie une représentation de la ressource Sheets associée.Mettez à jour les valeurs dans un établissement en spécifiant les métadonnées associées : par exemple, au lieu de mettre à jour les valeurs d'une ligne à l'aide de la notation A1, mettez à jour les valeurs en indiquant un ID de métadonnées.
Lire et écrire des métadonnées
La ressource spreadsheets.developerMetadata permet d'accéder aux métadonnées de développement associées à un lieu ou à un objet dans une feuille de calcul.
À propos des métadonnées du développeur
Cette section décrit certains aspects clés des métadonnées de développement que vous devez prendre en compte lorsque vous utilisez l'API Sheets.
Métadonnées sous forme de tags
Les métadonnées de développement peuvent être utilisées à l'aide d'une balise qui nomme un emplacement dans la feuille de calcul uniquement à l'aide d'une clé et d'un emplacement. Par exemple, vous pouvez associer headerRow à une ligne particulière ou totals à une colonne particulière au sein d'une feuille. Les balises peuvent être utilisées pour lier sémantiquement des parties d'une feuille de calcul à des champs d'un outil ou d'une base de données tiers, afin que les modifications apportées à la feuille de calcul n'affecteront pas votre application.
Métadonnées en tant que propriétés
Les métadonnées créées en spécifiant une clé, un emplacement et une valeur agissent comme une paire clé/valeur associée à cet emplacement dans une feuille. Par exemple, vous pouvez associer les éléments suivants:
formResponseId = resp123avec une lignelastUpdated = 1477369882par une colonne.
Cela vous permet de stocker des propriétés nommées personnalisées associées à des zones ou des données spécifiques dans une feuille de calcul et d'y accéder.
Métadonnées visibles au niveau du projet ou du document
Pour éviter qu'un projet de développeur interfère avec les métadonnées d'un autre, il existe deux paramètres de métadonnées visibility: project et document. Avec l'API Sheets, les métadonnées d'un projet ne sont visibles et accessibles qu'à partir du projet de développement qui les a créées. Les métadonnées du document sont accessibles à partir de n'importe quel projet de développement ayant accès au document.
Les requêtes qui ne spécifient pas explicitement de visibilité renvoient les métadonnées de document correspondantes et les métadonnées de projet correspondantes pour le projet de développeur à l'origine de la requête.
Originalité
Les clés de métadonnées n'ont pas besoin d'être uniques, mais l'élément metadataId doit être distinct. Si vous créez des métadonnées et que vous ne spécifiez pas le champ d'ID, l'API en attribue une. Cet ID peut servir à identifier les métadonnées, tandis que les clés et d'autres attributs peuvent servir à identifier des ensembles de métadonnées.
Créer des métadonnées
Pour créer des métadonnées, utilisez la méthode batchUpdate et fournissez un createDeveloperMetadataRequest avec metadataKey, location et visibility. Vous pouvez éventuellement spécifier un metadataValue ou un metadataId explicite.
Si vous spécifiez un ID déjà utilisé, la requête échouera. Si vous ne fournissez pas d'ID, l'API en attribue un.
Afficher un exemple
Dans cet exemple, nous fournissons dans la requête une clé, une valeur et une ligne. La réponse renvoie ces valeurs de métadonnées de développeur, plus l'ID de métadonnées attribué.
Requête
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}
Réponse
{
"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"
}
}
}
]
}
Lire un seul élément de métadonnées
Pour récupérer une seule métadonnée de développeur distincte, utilisez la méthode spreadsheets.developerMetadata.get, en spécifiant le spreadsheetId contenant les métadonnées et le metadataId unique des métadonnées du développeur.
Afficher un exemple
Requête
Dans cet exemple, nous fournissons l'ID de la feuille de calcul et l'ID des métadonnées dans la requête. La réponse renvoie les valeurs de métadonnées du développeur pour l'ID de métadonnées.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
Réponse
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
Lire plusieurs éléments de métadonnées
Pour récupérer plusieurs éléments de métadonnées de développeur, utilisez la méthode spreadsheets.developerMetadata.search. Vous devez spécifier un DataFilter qui correspond à toutes les métadonnées existantes sur n'importe quelle combinaison de propriétés telles que la clé, la valeur, l'emplacement ou la visibilité.
Afficher un exemple
Dans cet exemple, nous fournissons plusieurs ID de métadonnées dans la requête. La réponse renvoie les valeurs des métadonnées du développeur pour chaque ID de métadonnées.
Requête
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Réponse
{
"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
}
}
]
}
]
}
Mettre à jour les métadonnées
Pour mettre à jour les métadonnées du développeur, utilisez la méthode spreadsheets.batchUpdate et fournissez un UpdateDeveloperMetadataRequest.
Vous devez spécifier un objet DataFilter qui cible les métadonnées à mettre à jour, un objet DeveloperMetadata avec les nouvelles valeurs et un masque de champ décrivant les champs à mettre à jour.
Afficher un exemple
Dans cet exemple, nous fournissons l'ID des métadonnées, l'ID de la feuille et une nouvelle clé de métadonnées dans la requête. La réponse renvoie ces valeurs de métadonnées de développeur, ainsi que la clé de métadonnées mise à jour.
Requête
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}
Réponse
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Supprimer les métadonnées
Pour supprimer les métadonnées de développement, utilisez la méthode batchUpdate et fournissez une requête DeleteDeveloperMetadataRequest.
Vous devez spécifier un DataFilter pour sélectionner les métadonnées que vous souhaitez supprimer.
Afficher un exemple
Dans cet exemple, nous fournissons l'ID de métadonnées dans la requête. La réponse renvoie les valeurs de métadonnées du développeur pour l'ID de métadonnées.
Pour confirmer que les métadonnées de développement sont supprimées, utilisez la méthode spreadsheets.developerMetadata.get, en spécifiant l'ID des métadonnées supprimées. Vous devriez recevoir une réponse avec le code d'état HTTP 404: Not Found, ainsi que le message "Aucune métadonnée de développeur avec l'ID metadataId.
Requête
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}
Réponse
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Lecture et écriture des valeurs associées aux métadonnées
Vous pouvez également récupérer et mettre à jour les valeurs de cellule dans des lignes et des colonnes en spécifiant les métadonnées de développement associées et les valeurs que vous souhaitez mettre à jour. Pour ce faire, utilisez la méthode appropriée ci-dessous avec un DataFilter correspondant.
Obtenir les valeurs de cellules par métadonnées
Pour obtenir des valeurs de cellule en fonction de métadonnées, utilisez la méthode spreadsheets.values.batchGetByDataFilter. Vous devez spécifier l'ID de la feuille de calcul et un ou plusieurs filtres de données qui correspondent aux métadonnées.
Afficher un exemple
Dans cet exemple, nous fournissons l'ID de métadonnées dans la requête. La réponse renvoie les valeurs de cellule de ligne (numéro de modèle, ventes mensuelles) pour l'ID de métadonnées.
Requête
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}
Réponse
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}
Obtenir une feuille de calcul par métadonnées
Lors de la récupération d'une feuille de calcul, vous pouvez renvoyer un sous-ensemble de données à l'aide de la méthode spreadsheets.getByDataFilter. Vous devez spécifier l'ID de la feuille de calcul et un ou plusieurs filtres de données qui correspondent aux métadonnées.
Cette requête fonctionne comme une requête "table GET" standard, sauf que la liste des métadonnées correspondant aux filtres de données spécifiés détermine quelles feuilles, données de grille et autres ressources d'objets contenant des métadonnées sont renvoyées. Si includeGridData est défini sur "true", les données de grille qui croisent les plages de grille spécifiées sont également renvoyées pour la feuille.
Afficher un exemple
Dans cet exemple, nous fournissons l'ID de métadonnées et définissons includeGridData sur "false" dans la requête. La réponse renvoie les propriétés de la feuille de calcul et de la feuille.
Requête
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}
Réponse
{
"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
}
Mettre à jour des valeurs par métadonnées
Pour mettre à jour les valeurs de cellule correspondant à des métadonnées spécifiques, utilisez la méthode spreadsheets.values.batchUpdateByDataFilter. Vous devez spécifier l'ID de la feuille de calcul (valueInputOption), ainsi qu'un ou plusieurs DataFilterValueRange correspondant aux métadonnées.
Afficher un exemple
Dans cet exemple, nous fournissons l'ID des métadonnées et les valeurs de ligne mises à jour dans la requête. La réponse renvoie à la fois les propriétés et les données mises à jour pour l'ID de métadonnées.
Requête
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}
Réponse
{
"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"
]
]
}
}
]
}
Effacer les valeurs par métadonnées
Pour effacer les valeurs de cellule correspondant à des métadonnées spécifiques, utilisez la méthode spreadsheets.values.batchClearByDataFilter. Vous devez spécifier un filtre de données pour sélectionner les métadonnées que vous voulez effacer.
Afficher un exemple
Requête
Dans cet exemple, nous fournissons l'ID de métadonnées dans la requête. La réponse renvoie l'ID de la feuille de calcul et les plages effacées.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Réponse
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
Limites de stockage des métadonnées
La quantité totale de métadonnées que vous pouvez stocker dans une feuille de calcul est limitée. Cette limite est mesurée en caractères et comprend deux éléments:
| Article | Allocation de la limite de stockage |
|---|---|
| Spreadsheet | 30 000 caractères |
| Chaque feuille d’une feuille de calcul | 30 000 caractères |
La feuille de calcul peut contenir jusqu'à 30 000 caractères. En outre, vous pouvez stocker 30 000 caractères pour chaque feuille d'une feuille de calcul (30 000 pour la feuille 1, 30 000 pour la feuille 2, etc.). Ainsi,une feuille de calcul de 3 pages peut contenir jusqu'à 120 000 caractères de métadonnées de développeur.
Chaque caractère des attributs de clé et de valeur d'un objet developerMetadata est comptabilisé dans cette limite.