Plages nommées & protégées

L'API Google Sheets vous permet de créer, modifier et supprimer des plages nommées ou protégées. Les exemples de cette page montrent comment effectuer certaines opérations Sheets courantes avec l'API Sheets.

Ces exemples sont présentés sous la forme de requêtes HTTP pour être neutres en ce qui concerne le langage. Pour découvrir comment implémenter une mise à jour groupée dans différents langages à l'aide des bibliothèques clientes de l'API Google, consultez Mettre à jour des feuilles de calcul.

Dans ces exemples, les espaces réservés SPREADSHEET_ID et SHEET_ID indiquent où vous devez fournir ces ID. L'ID de la feuille de calcul se trouve dans son URL. Vous pouvez obtenir l'ID de la feuille à l'aide de la méthode spreadsheets.get. Ces plages sont spécifiées au format A1. Exemple de plage : Feuille1!A1:D5.

De plus, les espaces réservés NAMED_RANGE_ID et PROTECTED_RANGE_ID fournissent les ID des plages nommées et protégées. namedRangeId et protectedRangeId sont utilisés lorsque vous envoyez des requêtes de mise à jour ou de suppression des plages associées. L'ID est renvoyé dans la réponse à une requête API Sheets qui crée une plage nommée ou protégée. Vous pouvez obtenir les ID des plages existantes à l'aide de la méthode spreadsheets.get, dans le corps de la réponse Spreadsheet.

Ajouter des plages nommées ou protégées

L'exemple de code spreadsheets.batchUpdate suivant montre comment utiliser deux objets de requête. La première utilise AddNamedRangeRequest pour attribuer le nom "Counts" à la plage A1:E3. La seconde utilise AddProtectedRangeRequest pour associer une protection de niveau avertissement à la plage A4:E4. Cette protection de niveau permet toujours de modifier les cellules de la plage, mais un avertissement s'affiche avant que la modification soit effectuée.

Ces requêtes renvoient les champs AddNamedRangeResponse et AddProtectedRangeResponse contenant les ID et les propriétés de la plage.

Le protocole de requête est illustré ci-dessous.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "addNamedRange": {
        "namedRange": {
          "name": "Counts",
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 0,
            "endRowIndex": 3,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
        }
      }
    },
    {
      "addProtectedRange": {
        "protectedRange": {
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 3,
            "endRowIndex": 4,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
          "description": "Protecting total row",
          "warningOnly": true
        }
      }
    }
  ]
}

Supprimer des plages nommées ou protégées

L'exemple de code spreadsheets.batchUpdate suivant montre comment utiliser deux objets de requête. La première utilise DeleteNamedRangeRequest pour supprimer une plage nommée existante, en utilisant l'NAMED_RANGE_ID d'un appel d'API précédent. La seconde utilise l'DeleteProtectedRangeRequest pour supprimer une protection de plage existante, en utilisant le PROTECTED_RANGE_ID d'un appel d'API précédent.

Le protocole de requête est illustré ci-dessous.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "deleteNamedRange": {
          "namedRangeId": "NAMED_RANGE_ID",
      }
    },
    {
      "deleteProtectedRange": {
        "protectedRangeId": PROTECTED_RANGE_ID,
      }
    }
  ]
}

Mettre à jour des plages nommées ou protégées

L'exemple de code spreadsheets.batchUpdate suivant montre comment utiliser deux objets de requête. La première utilise UpdateNamedRangeRequest pour mettre à jour le nom d'une plage nommée existante en "InitialCounts", en utilisant l'NAMED_RANGE_ID d'un appel d'API précédent. La seconde utilise UpdateProtectedRangeRequest pour mettre à jour une plage protégée existante afin qu'elle protège désormais la même plage nommée. La méthode Editors permet uniquement aux utilisateurs répertoriés de modifier ces cellules. Cette requête utilise les valeurs NAMED_RANGE_ID et PROTECTED_RANGE_ID des appels d'API précédents.

Le protocole de requête est illustré ci-dessous.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "updateNamedRange": {
        "namedRange": {
          "namedRangeId": NAMED_RANGE_ID,
          "name": "InitialCounts",
        },
        "fields": "name",
      }
    },
    {
      "updateProtectedRange": {
        "protectedRange": {
          "protectedRangeId": PROTECTED_RANGE_ID,
          "namedRangeId": NAMED_RANGE_ID,
          "warningOnly": false,
          "editors": {
            "users": [
              "charlie@example.com",
              "sasha@example.com"
            ]
          }
        },
        "fields": "namedRangeId,warningOnly,editors"
      }
    }
  ]
}