Fusionner du texte dans un document

L'API Google Docs est particulièrement utile pour fusionner des informations provenant d'une ou de plusieurs sources de données dans un document.

Cette page explique comment récupérer des données à partir d'une source externe et les insérer dans un document modèle existant.

Un modèle est un type spécial de document contenant le même texte fixe pour tous les documents créés à partir du modèle, ainsi que des espaces réservés désignés où d'autres textes dynamiques peuvent être placés. Par exemple, un modèle de contrat peut contenir du contenu fixe, ainsi que des emplacements pour le nom, l'adresse et d'autres informations du destinataire. Votre application peut ensuite fusionner des données spécifiques au client dans le modèle pour créer des documents finis.

Cette approche présente plusieurs avantages :

  • Les concepteurs peuvent facilement affiner la conception d'un document à l'aide de l'éditeur Google Docs. C'est beaucoup plus simple que de régler les paramètres de votre application pour définir la mise en page rendue.

  • La séparation du contenu et de la présentation est un principe de conception bien connu qui présente de nombreux avantages.

Schéma conceptuel d'une fusion.

Recette de base

Voici un exemple d'utilisation de l'API Docs pour fusionner des données dans un document :

  1. Créez votre document à l'aide d'un contenu d'espace réservé pour vous aider à concevoir et à mettre en forme. Toute mise en forme de texte que vous souhaitez remplacer est conservée.

  2. Pour chaque élément que vous insérerez, remplacez le contenu de l'espace réservé par un tag. Veillez à utiliser des chaînes qui ne sont pas susceptibles de se produire normalement. Par exemple, {{account-holder-name}} peut être un bon tag.

  3. Dans votre code, utilisez l'API Google Drive pour créer une copie du document.

  4. Dans votre code, utilisez la méthode batchUpdate() de l'API Docs avec le nom du document et incluez un ReplaceAllTextRequest.

Les ID de document font référence à un document et peuvent être dérivés de l'URL.

https://docs.google.com/document/d/DOCUMENT_ID/edit
 .

Exemple

Prenons l'exemple suivant, qui remplace deux champs dans tous les onglets d'un modèle par des valeurs réelles pour générer un document final.

Pour effectuer cette fusion, vous pouvez utiliser le code ci-dessous.

Java

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

List requests = new ArrayList<>();
// One option for replacing all text is to specify all tab IDs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{customer-name}}")
                        .setMatchCase(true))
                .setReplaceText(customerName)
                .setTabsCriteria(new TabsCriteria()
                        .addTabIds(TAB_ID_1)
                        .addTabIds(TAB_ID_2)
                        .addTabIds(TAB_ID_3))));
// Another option is to omit TabsCriteria if you are replacing across all tabs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{date}}")
                        .setMatchCase(true))
                .setReplaceText(date)));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(DOCUMENT_ID, body.setRequests(requests)).execute();

Node.js

  let customerName = 'Alice';
  let date = yyyymmdd()
  let requests = [
    // One option for replacing all text is to specify all tab IDs.
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        },
      },
    },
    // Another option is to omit TabsCriteria if you are replacing across all tabs.
    {
      replaceAllText: {
        containsText: {
          text: '{{date}}',
          matchCase: true,
        },
        replaceText: date,
      },
    },
  ];

  google.options({auth: auth});
  google
      .discoverAPI(
          'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')
      .then(function(docs) {
        docs.documents.batchUpdate(
            {
              documentId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
              resource: {
                requests,
              },
            },
            (err, {data}) => {
              if (err) return console.log('The API returned an error: ' + err);
              console.log(data);
            });
      });

Python

customer_name = 'Alice'
date = datetime.datetime.now().strftime("%y/%m/%d")

requests = [
        # One option for replacing all text is to specify all tab IDs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{customer-name}}',
                'matchCase':  'true'
            },
            'replaceText': customer_name,
            'tabsCriteria': {
                'tabIds': [TAB_ID_1, TAB_ID_2, TAB_ID_3],
            },
        }},
        # Another option is to omit TabsCriteria if you are replacing across all tabs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{date}}',
                'matchCase':  'true'
            },
            'replaceText': str(date),
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Gérer les modèles

Pour les documents modèles que l'application définit et possède, créez le modèle à l'aide d'un compte dédié représentant l'application. Les comptes de service sont un bon choix et évitent les complications liées aux règles Google Workspace qui limitent le partage.

Lorsque vous créez des instances de documents à partir de modèles, utilisez toujours les identifiants de l'utilisateur final. Les utilisateurs peuvent ainsi contrôler pleinement le document résultant et éviter les problèmes de scaling liés aux limites par utilisateur dans Drive.

Pour créer un modèle à l'aide d'un compte de service, procédez comme suit avec les identifiants de l'application :

  1. Créez un document à l'aide de documents.create dans l'API Docs.
  2. Mettez à jour les autorisations pour permettre aux destinataires du document de le lire à l'aide de permissions.create dans l'API Drive.
  3. Mettez à jour les autorisations pour permettre aux auteurs du modèle d'y écrire à l'aide de permissions.create dans l'API Drive.
  4. Modifiez le modèle selon vos besoins.

Pour créer une instance du document, procédez comme suit avec les identifiants de l'utilisateur :

  1. Créez une copie du modèle à l'aide de files.copy dans l' API Drive.
  2. Remplacez les valeurs à l'aide de documents.batchUpdate dans l'API Docs.