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 extraire des données d'une source externe et les insérer dans un document de modèle existant.
Un modèle est un type de document spécial 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 avoir un 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 au client dans le modèle pour créer des documents finalisés.
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 d'ajuster les paramètres de votre application pour définir la mise en page affichée.
La séparation du 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 à l'aide de contenus d'espace réservé pour vous aider à concevoir et à mettre en forme. La mise en forme du texte que vous souhaitez remplacer est conservée.
Pour chaque élément que vous allez insérer, remplacez le contenu de l'espace réservé par une balise. Veillez à utiliser des chaînes qui ne sont pas susceptibles de s'afficher normalement. Par exemple,
{{account-holder-name}}peut être un bon tag.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 dans tous les onglets 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<>();
// 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 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 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. Cela permet aux utilisateurs de contrôler entièrement le document obtenu et d'é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 autoriser les destinataires du document à le lire à l'aide de permissions.create dans l'API Drive.
- Mettez à jour les autorisations pour autoriser les auteurs de modèles à y écrire à l'aide de permissions.create dans l'API Drive.
- Modifiez le modèle si nécessaire.
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.