Cette page a été traduite par l'API Cloud Translation.

Fusionner du texte dans un document

L'API Google Docs peut être utilisée pour fusionner des informations provenant d'une ou de plusieurs sources de données dans un document.

Cette page explique comment insérer des données provenant d'une source externe dans un document modèle existant.

Un modèle est un type de document spécial qui contient 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 les données spécifiques aux clients dans le modèle pour créer des documents finaux.

Cette approche est utile pour plusieurs raisons :

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 affichée.
La séparation du contenu et de la présentation est un principe de conception bien connu qui présente de nombreux avantages.

Diagramme conceptuel d'une fusion.

Recette de base

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

Créez votre document en utilisant du contenu de substitution pour vous aider à concevoir la mise en page et la mise en forme. Toute mise en forme de texte que vous souhaitez remplacer est conservée.
Pour chaque élément que vous insérerez, remplacez le contenu de l'espace réservé par un tag. Veillez à utiliser des chaînes peu susceptibles de se produire normalement. Par exemple, {{account-holder-name}} peut être une bonne balise.
Dans votre code, utilisez l'API Google Drive pour copier le document.
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/documentId/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<Request> 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(documentId, 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 permettent d'éviter 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 des identifiants d'utilisateur final. Les utilisateurs ont ainsi un contrôle total sur le document obtenu et peuvent éviter les problèmes de mise à l'échelle 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 :

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

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

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