La fonctionnalité de métadonnées pour les développeurs vous permet d'associer des métadonnées à diverses entités et zones géographiques dans une feuille de calcul. Vous pouvez ensuite interroger ces métadonnées et les utiliser pour trouver 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 pour les développeurs vous permettent d'effectuer les opérations suivantes:
Associer des données arbitraires à diverses entités et emplacements dans une feuille de calcul : par exemple, associez
totalsà la colonne D ouresponseId = 1234à la ligne 7.Rechercher tous les emplacements et les données associés à une clé ou à un attribut de métadonnées particulier : par exemple, étant donné la clé
totalsassociée à la colonne D ou étant donnéresponseId, renvoyez toutes les lignes avec les métadonnéesresponseIdet la valeur de métadonnées qui leur est associée.Rechercher toutes les données associées à une entité ou à un emplacement spécifique : par exemple, pour la colonne D, renvoyez toutes les métadonnées associées à cet emplacement.
Récupérer des valeurs dans un emplacement en spécifiant les métadonnées associées : par exemple, étant donné
totals, renvoyez une représentation des valeurs contenues dans la colonne ou la ligne associée, ou étant donnésummary, renvoyez une représentation de la ressource de feuille associée.Mettre à jour les valeurs à un emplacement 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, indiquez 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 établissement ou à un objet dans une feuille de calcul.
À propos des métadonnées de développeur
Cette section décrit certains aspects clés des métadonnées de développeur que vous devez prendre en compte lorsque vous utilisez l'API Sheets.
Métadonnées sous forme de balises
Les métadonnées pour les développeurs peuvent être utilisées pour créer une balise qui nomme un emplacement dans la feuille de calcul à l'aide d'une clé et d'un emplacement uniquement. Par exemple, vous pouvez associer headerRow à une ligne spécifique ou totals à une colonne spécifique dans une feuille. Les balises peuvent être utilisées pour lier sémantiquement des parties d'une feuille de calcul à des champs dans un outil ou une base de données tiers. Ainsi, les modifications apportées à la feuille de calcul ne perturberont 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:
formResponseId = resp123avec une lignelastUpdated = 1477369882avec une colonne.
Vous pouvez ainsi stocker et accéder à des propriétés nommées personnalisées associées à des zones ou des données spécifiques dans une feuille de calcul.
Métadonnées visibles du projet par rapport aux métadonnées du document
Pour éviter qu'un projet de développeur n'interfère avec les métadonnées d'un autre, il existe deux paramètres visibility de métadonnées: project et document. Avec l'API Sheets, les métadonnées du projet ne sont visibles et accessibles que depuis le projet du développeur qui l'a créé. Les métadonnées du document sont accessibles depuis n'importe quel projet de développeur ayant accès au document.
Les requêtes qui ne spécifient pas explicitement une visibilité renvoient les métadonnées de document et les métadonnées de projet correspondantes pour le projet du développeur à l'origine de la requête.
Unicité
Les clés de métadonnées ne doivent pas nécessairement être uniques, mais les metadataId doivent être distinctes. Si vous créez des métadonnées et laissez leur champ d'ID non spécifié, l'API en attribue un. Cet ID peut être utilisé pour identifier les métadonnées, tandis que les clés et d'autres attributs peuvent être utilisés pour 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 une createDeveloperMetadataRequest avec un metadataKey, un location et un 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 une clé, une valeur et une ligne dans la requête. La réponse renvoie ces valeurs de métadonnées de développeur, ainsi que 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"
}
}
}
]
}Response (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ées 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 de 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 des métadonnées de développement pour l'ID des métadonnées.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
Response (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 pour toute 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 de développement pour chaque ID de métadonnées.
Requête
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Response (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 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 de 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"
}
}
]
}Response (Réponse)
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Supprimer des métadonnées
Pour supprimer des métadonnées de développeur, utilisez la méthode batchUpdate et fournissez un 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 des métadonnées de développement pour l'ID des métadonnées.
Pour vérifier que les métadonnées du développeur ont été 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, avec le message "Aucune métadonnées de développeur associée à l'ID metadataId.
Requête
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}Response (Réponse)
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Lire et écrire les valeurs associées aux métadonnées
Vous pouvez également récupérer et mettre à jour les valeurs des cellules dans les lignes et les colonnes en spécifiant les métadonnées du développeur 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 des cellules par métadonnées
Pour obtenir les valeurs des cellules par 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 correspondant 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 des cellules de la ligne (numéro de modèle, ventes mensuelles) pour l'ID de métadonnées.
Requête
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}Response (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
Lorsque vous récupérez 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 correspondant aux métadonnées.
Cette requête fonctionne comme une requête "GET de feuille de calcul" standard, sauf que la liste des métadonnées correspondant aux filtres de données spécifiés détermine les feuilles, les données de grille et les autres ressources d'objets avec métadonnées qui 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 à la fois les propriétés de la feuille de calcul et de la feuille.
Requête
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}Response (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 les 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, et un ou plusieurs DataFilterValueRange correspondant aux métadonnées.
Afficher un exemple
Dans cet exemple, nous fournissons l'ID de 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"
}Response (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 souhaitez 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
}
}
]
}Response (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 se compose de deux composants:
| Élément | Allocation de la limite de stockage |
|---|---|
| Feuille de calcul | 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. De plus, vous pouvez stocker 30 000 caractères pour chaque feuille d'une feuille de calcul (30 000 caractères pour la première feuille, 30 000 caractères pour la deuxième feuille, etc.). Ainsi,une feuille de calcul de trois pages peut contenir jusqu'à 120 000 caractères de métadonnées pour les développeurs.
Chaque caractère des attributs de clé et de valeur d'un objet developerMetadata est pris en compte dans cette limite.