Plages nommées & protégées

L'API Google Sheets vous permet de créer, de modifier et de supprimer des plages nommées ou protégées. Les exemples de cette page illustrent 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 indépendants du langage. Pour découvrir comment implémenter une mise à jour par lot dans différents langages à l'aide de s 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. Vous trouverez l'ID de la feuille de calcul dans son URL. Vous pouvez obtenir l'ID de la feuille à l'aide de la spreadsheets.get méthode. Les plages sont spécifiées à l'aide de la notation A1. Par exemple, Sheet1!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. Les namedRangeId et protectedRangeId sont utilisés lors de l'envoi de requêtes pour mettre à jour ou supprimer les plages associées. L'ID est renvoyé dans la réponse à une requête de l'API Sheets qui crée une plage nommée ou protégée. Vous pouvez obtenir les ID des plages existantes avec la spreadsheets.get méthode, dans le Spreadsheet corps de la réponse.

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

L'exemple de code spreadsheets.batchUpdate suivant montre comment utiliser deux objets de requête. Le premier utilise les AddNamedRangeRequest pour attribuer le nom "Counts" à la plage A1:E3. Le deuxième utilise les AddProtectedRangeRequest pour appliquer une protection de niveau avertissement à la plage A4:E4. Ce niveau de protection permet toujours de modifier les cellules de la plage, mais affiche un avertissement avant d'effectuer la modification.

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

Le protocole de requête est présenté 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. Le premier utilise les DeleteNamedRangeRequest pour supprimer une plage nommée existante, à l'aide des NAMED_RANGE_ID d'un appel d'API précédent. Le deuxième utilise les DeleteProtectedRangeRequest pour supprimer une protection de plage existante, à l'aide des PROTECTED_RANGE_ID d'un appel d'API précédent.

Le protocole de requête est présenté 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. Le premier utilise les UpdateNamedRangeRequest pour remplacer le nom d'une plage nommée existante par "InitialCounts", à l'aide des NAMED_RANGE_ID d'un appel d'API précédent. Le deuxième utilise le UpdateProtectedRangeRequest pour mettre à jour une plage protégée existante afin qu'elle protège désormais la même plage nommée. La Editors méthode permet uniquement aux utilisateurs listés de modifier ces cellules. Cette requête utilise les NAMED_RANGE_ID et PROTECTED_RANGE_ID des appels d'API précédents.

Le protocole de requête est présenté 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"
      }
    }
  ]
}