W tym przewodniku wyjaśniono, jak za pomocą interfejsu API Dokumentów Google wykonać scalenie poczty.
Wstęp
Narzędzie do kreatora e-maili pobiera wartości z wierszy arkusza kalkulacyjnego lub innego źródła danych i wstawia je do dokumentu szablonu. Dzięki temu możesz utworzyć jeden dokument główny (szablon), na podstawie którego możesz wygenerować wiele podobnych dokumentów, z których każdy będzie dostosowany do scalonych danych. Wynik ten nie musi być używany w przypadku e-maili ani listów formularzy, ale może służyć do innych celów, takich jak generowanie grupy faktur dla klientów.
Kreator e-maili jest stosowany od dawna, gdy powstały arkusze kalkulacyjne i edytory tekstu, a obecnie stanowi część wielu procesów biznesowych. Dane są uporządkowane w formie 1 rekordu na wiersz, gdzie kolumny reprezentują pola danych, jak w tej tabeli:
Nazwa
Adres
Strefa
1
UrbanPq
ul. Polna 123
zachód
2
Pawxana
456 2nd St.
południe
Przykładowa aplikacja na tej stronie pokazuje, jak za pomocą interfejsów API Dokumentów, Arkuszy i Dysku Google uniknąć szczegółów działania kreatora e-maili, co chroni użytkowników przed wątpliwościami dotyczącymi implementacji. Więcej informacji o tym przykładzie w Pythonie znajdziesz w repozytorium GitHub.
Przykładowa aplikacja
Ta przykładowa aplikacja kopiuje podstawowy szablon, a następnie scala zmienne ze wskazanego źródła danych z każdą z kopii. Aby wypróbować tę przykładową aplikację, najpierw skonfiguruj szablon:
Zapisz identyfikator dokumentu nowego pliku. Więcej informacji znajdziesz w sekcji Identyfikator dokumentu.
Ustaw zmienną DOCS_FILE_ID na identyfikator dokumentu.
Zastąp informacje kontaktowe zmiennymi zastępczymi szablonu, które aplikacja będzie scalać z wybranymi danymi.
Oto przykładowy szablon listu ze zmiennymi, które można połączyć z prawdziwymi danymi ze źródła, np. zwykłego tekstu lub Arkuszy. Tak wygląda ten szablon:
Następnie jako źródło danych wybierz zwykły tekst lub Arkusze, korzystając ze zmiennej SOURCE. Przykładem jest domyślnie zwykły tekst, co oznacza, że przykładowe dane korzystają ze zmiennej TEXT_SOURCE_DATA. Aby pobrać dane z Arkuszy, zaktualizuj zmienną SOURCE do wartości 'sheets' i wskaż nasz przykładowy arkusz (lub Twój) za pomocą zmiennej SHEETS_FILE_ID.
Oto jak wygląda arkusz, aby można było zobaczyć jego format:
Wypróbuj aplikację na podstawie naszych przykładowych danych, a potem dostosuj ją do swoich danych i przypadku użycia. Aplikacja wiersza poleceń działa w ten sposób:
Konfiguracja
Pobierz dane ze źródła danych
Zapętlanie kolejnych wierszy danych
Utwórz kopię szablonu
Scal kopię z danymi
Link wyjściowy do nowo scalonego dokumentu
Wszystkie nowo scalone litery będą też widoczne na Moim dysku użytkownika. Przykład scalonej litery wygląda mniej więcej tak:
import time
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
# Fill-in IDs of your Docs template & any Sheets data source
DOCS_FILE_ID = "195j9eDD3ccgjQRttHhJPymLJUCOUjs-jmwTrekvdjFE"
SHEETS_FILE_ID = "11pPEzi1vCMNbdpqaQx4N43rKmxvZlgEHE9GqpYoEsWw"
# authorization constants
SCOPES = ( # iterable or space-delimited string
"https://www.googleapis.com/auth/drive",
"https://www.googleapis.com/auth/documents",
"https://www.googleapis.com/auth/spreadsheets.readonly",
)
# application constants
SOURCES = ("text", "sheets")
SOURCE = "text" # Choose one of the data SOURCES
COLUMNS = ["to_name", "to_title", "to_company", "to_address"]
TEXT_SOURCE_DATA = (
(
"Ms. Lara Brown",
"Googler",
"Google NYC",
"111 8th Ave\nNew York, NY 10011-5201",
),
(
"Mr. Jeff Erson",
"Googler",
"Google NYC",
"76 9th Ave\nNew York, NY 10011-4962",
),
)
# fill-in your data to merge into document template variables
merge = {
# sender data
"my_name": "Ayme A. Coder",
"my_address": "1600 Amphitheatre Pkwy\nMountain View, CA 94043-1351",
"my_email": "http://google.com",
"my_phone": "+1-650-253-0000",
# - - - - - - - - - - - - - - - - - - - - - - - - - -
# recipient data (supplied by 'text' or 'sheets' data source)
"to_name": None,
"to_title": None,
"to_company": None,
"to_address": None,
# - - - - - - - - - - - - - - - - - - - - - - - - - -
"date": time.strftime("%Y %B %d"),
# - - - - - - - - - - - - - - - - - - - - - - - - - -
"body": (
"Google, headquartered in Mountain View, unveiled the new "
"Android phone at the Consumer Electronics Show. CEO Sundar "
"Pichai said in his keynote that users love their new phones."
),
}
creds, _ = google.auth.default()
# pylint: disable=maybe-no-member
# service endpoints to Google APIs
DRIVE = build("drive", "v2", credentials=creds)
DOCS = build("docs", "v1", credentials=creds)
SHEETS = build("sheets", "v4", credentials=creds)
def get_data(source):
"""Gets mail merge data from chosen data source."""
try:
if source not in {"sheets", "text"}:
raise ValueError(
f"ERROR: unsupported source {source}; choose from {SOURCES}"
)
return SAFE_DISPATCH[source]()
except HttpError as error:
print(f"An error occurred: {error}")
return error
def _get_text_data():
"""(private) Returns plain text data; can alter to read from CSV file."""
return TEXT_SOURCE_DATA
def _get_sheets_data(service=SHEETS):
"""(private) Returns data from Google Sheets source. It gets all rows of
'Sheet1' (the default Sheet in a new spreadsheet), but drops the first
(header) row. Use any desired data range (in standard A1 notation).
"""
return (
service.spreadsheets()
.values()
.get(spreadsheetId=SHEETS_FILE_ID, range="Sheet1")
.execute()
.get("values")[1:]
)
# skip header row
# data source dispatch table [better alternative vs. eval()]
SAFE_DISPATCH = {k: globals().get(f"_get_{k}_data") for k in SOURCES}
def _copy_template(tmpl_id, source, service):
"""(private) Copies letter template document using Drive API then
returns file ID of (new) copy.
"""
try:
body = {"name": f"Merged form letter ({source})"}
return (
service.files()
.copy(body=body, fileId=tmpl_id, fields="id")
.execute()
.get("id")
)
except HttpError as error:
print(f"An error occurred: {error}")
return error
def merge_template(tmpl_id, source, service):
"""Copies template document and merges data into newly-minted copy then
returns its file ID.
"""
try:
# copy template and set context data struct for merging template values
copy_id = _copy_template(tmpl_id, source, service)
context = merge.iteritems() if hasattr({}, "iteritems") else merge.items()
# "search & replace" API requests for mail merge substitutions
reqs = [
{
"replaceAllText": {
"containsText": {
"text": "{{%s}}" % key.upper(), # {{VARS}} are uppercase
"matchCase": True,
},
"replaceText": value,
}
}
for key, value in context
]
# send requests to Docs API to do actual merge
DOCS.documents().batchUpdate(
body={"requests": reqs}, documentId=copy_id, fields=""
).execute()
return copy_id
except HttpError as error:
print(f"An error occurred: {error}")
return error
if __name__ == "__main__":
# get row data, then loop through & process each form letter
data = get_data(SOURCE) # get data from data source
for i, row in enumerate(data):
merge.update(dict(zip(COLUMNS, row)))
print(
"Merged letter %d: docs.google.com/document/d/%s/edit"
% (i + 1, merge_template(DOCS_FILE_ID, SOURCE, DRIVE))
)
Więcej informacji znajdziesz w pliku README i pełnym kodzie źródłowym aplikacji w repozytorium GitHub przykładowej aplikacji.
