Une application utile de l'API Google Docs consiste à fusionner les informations d'une ou de plusieurs sources de données dans un document.
Cette page explique comment récupérer des données d'une source externe et les insérer dans un modèle de document existant.
Un modèle est un type de document spécial contenant le même texte fixe pour tous les documents créés à partir de celui-ci, ainsi que des espaces réservés désignés dans lesquels d'autres textes dynamiques peuvent être placés. Par exemple, un modèle de contrat peut avoir un contenu fixe, ainsi que des emplacements pour le nom, l'adresse et d'autres détails du destinataire. Votre application peut ensuite fusionner les données spécifiques au client dans le modèle pour créer des documents finalisés.
Cette approche est utile pour plusieurs raisons:
Les graphistes peuvent facilement peaufiner la conception d'un document à l'aide de l'éditeur Google Docs. C'est beaucoup plus simple que de régler des paramètres dans votre application pour définir la mise en page affichée.
Séparer le contenu de la présentation est un principe de conception bien connu qui présente de nombreux avantages.
Une 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 d'espace réservé pour vous aider à le concevoir et à le mettre en forme. La mise en forme du texte que vous souhaitez remplacer est conservée.
Pour chaque élément que vous insérez, remplacez le contenu de l'espace réservé par une balise. Assurez-vous d'utiliser des chaînes qui sont 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 créer une copie du document.
Dans votre code, utilisez la méthode
batchUpdate()de l'API Docs avec le nom du document et incluez unReplaceAllTextRequest.
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 d'un modèle par des valeurs réelles pour générer un document finalisé.
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<>();
requests.add(new Request()
.setReplaceAllText(new ReplaceAllTextRequest()
.setContainsText(new SubstringMatchCriteria()
.setText("{{customer-name}}")
.setMatchCase(true))
.setReplaceText(customerName)));
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 = [
{
replaceAllText: {
containsText: {
text: '{{customer-name}}',
matchCase: true,
},
replaceText: customerName,
},
},
{
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 = [
{
'replaceAllText': {
'containsText': {
'text': '{{customer-name}}',
'matchCase': 'true'
},
'replaceText': customer_name,
}}, {
'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 de modèle 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 constituent un bon choix et évitent les complications avec les 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. Cela donne aux utilisateurs un contrôle total sur le document obtenu et évite 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:
- 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 des valeurs à l'aide de documents.batchUpdate dans l'API Docs.