Lire et écrire les métadonnées pour les développeurs

La fonctionnalité de métadonnées de développeur vous permet d'associer des métadonnées à différentes entités et différents emplacements d'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 de développeur vous permettent d'effectuer des opérations telles que :

  • Associez des données arbitraires à différentes entités et différents lieux dans une feuille de calcul. Par exemple, associez totals à la colonne D ou responseId = 1234 à la ligne 7.

  • Trouver tous les emplacements et toutes les données associés à une clé ou un attribut de métadonnées spécifique : par exemple, étant donné la clé totals associée à la colonne D ou étant donné responseId, renvoyer toutes les lignes avec les métadonnées responseId et la valeur de métadonnées associée.

  • Trouver toutes les données associées à une entité ou un lieu spécifique : par exemple, pour la colonne D, renvoyer toutes les métadonnées associées à ce lieu.

  • Récupérer des valeurs dans un emplacement en spécifiant les métadonnées associées : par exemple, étant donné totals, renvoyer une représentation des valeurs contenues dans la colonne ou la ligne associée, ou étant donné summary, renvoyer une représentation de la ressource Sheet associée.

  • Mettre à jour les valeurs d'un lieu 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 emplacement 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 à prendre en compte lorsque vous utilisez l'API Sheets.

Métadonnées sous forme de tags

Les métadonnées de développeur peuvent être utilisées comme tag pour nommer 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 d'une feuille. Les tags peuvent être utilisés 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 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 :

  • formResponseId = resp123 avec une ligne
  • lastUpdated = 1477369882 avec une colonne.

Vous pouvez ainsi stocker et accéder à des propriétés personnalisées nommées associées à des zones ou des données spécifiques d'une feuille de calcul.

Métadonnées visibles au niveau du projet ou 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 : project et document. Avec l'API Sheets, les métadonnées du projet ne sont visibles et accessibles que depuis le projet de développeur qui les a créées. 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 de visibilité renvoient les métadonnées de document correspondantes et les métadonnées de projet correspondantes pour le projet de développeur qui effectue la requête.

Unicité

Les clés de métadonnées n'ont pas besoin d'être uniques, mais les metadataId doivent être distincts. Si vous créez des métadonnées et que vous ne spécifiez pas leur champ d'ID, l'API en attribue un. Cet ID peut être utilisé pour identifier les métadonnées, tandis que les clés et 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 un 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.

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

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 la spreadsheetId contenant les métadonnées et le metadataId unique des métadonnées de développeur.

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

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 devrez 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é.

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é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 devrez spécifier un DataFilter ciblant les métadonnées à mettre à jour, un objet DeveloperMetadata avec les nouvelles valeurs et un masque de champ décrivant les champs à mettre à jour.

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 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.

Dans cet exemple, nous fournissons 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.

Pour vérifier que les métadonnées de 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 un code d'état HTTP 404: Not Found, avec un message indiquant "Aucune métadonnée de développeur ne porte 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"
          }
        ]
      }
    }
  ]
}

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 de 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.

Dans cet exemple, nous fournissons l'ID des métadonnées dans la requête. La réponse renvoie les valeurs des cellules 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

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'objet avec métadonnées qui sont renvoyées. Si includeGridData est défini sur "true", les données de grille croisant les plages de grille spécifiées sont également renvoyées pour la feuille.

Dans cet exemple, nous fournissons l'ID des 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
}

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 cellules 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.

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 cellules correspondant à des métadonnées spécifiques, utilisez la méthode spreadsheets.values.batchClearByDataFilter. Vous devrez spécifier un filtre de données pour sélectionner les métadonnées que vous souhaitez effacer.

Requête

Dans cet exemple, nous fournissons l'ID des 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 exprimée en nombre de caractères et se compose de deux éléments :

É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

Vous pouvez stocker jusqu'à 30 000 caractères pour la feuille de calcul. De plus, vous pouvez stocker 30 000 caractères pour chaque feuille d'un même tableur (30 000 pour la première feuille, 30 000 pour la deuxième, etc.). Une feuille de calcul de trois pages peut donc 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.