Kreator e-maili za pomocą interfejsu API Dokumentów

Z tego przewodnika dowiesz się, jak użyć interfejsu Google Docs API do wykonania scalania wiadomości e-mail.

Wprowadzenie

Zbiorcze wiadomości pobierają wartości z wierszy arkusza kalkulacyjnego lub innego źródła danych i wstawiają je do dokumentu szablonu. Dzięki temu możesz utworzyć jeden główny dokument (szablon), na podstawie którego możesz wygenerować wiele podobnych dokumentów, z których każdy będzie dostosowany do danych, które mają być scalone. Wynik nie musi być używany do wysyłania e-maili ani listów, ale może służyć do dowolnego celu, np. do generowania partii faktur dla klientów.

Korespondencja zbiorcza istnieje od czasów, gdy pojawiły się arkusze kalkulacyjne i edytory tekstu, i jest obecnie częścią wielu procesów biznesowych. Zgodnie z konwencją dane są uporządkowane w taki sposób, że każdy wiersz zawiera 1 rekord, a kolumny reprezentują pola danych, jak pokazano w tabeli poniżej:

Nazwa Adres Strefa
1 UrbanPq 123 ul. Pierwsza zachód
2 Pawxana 456 2nd St. południe

Przykładowa aplikacja na tej stronie pokazuje, jak można używać interfejsów Google Docs, Arkuszy i Dysku, aby ukryć szczegóły dotyczące tego, jak odbywa się scalanie wiadomości e-mail, i chronić użytkowników przed problemami związanymi z implementacją. Więcej informacji o tym przykładzie kodu Pythona znajdziesz w repozytorium GitHub.

Przykładowa aplikacja

Ta przykładowa aplikacja kopiuje główny szablon, a następnie scala zmienne z wybranego źródła danych z każdą z kopii. Aby wypróbować tę przykładową aplikację, najpierw skonfiguruj szablon:

  1. Utwórz plik Dokumentów. Wybierz szablon, którego chcesz użyć.
  2. Zanotuj identyfikator dokumentu nowego pliku. Więcej informacji znajdziesz w sekcji Identyfikator dokumentu.
  3. Ustaw zmienną DOCS_FILE_ID na identyfikator dokumentu.
  4. Zastąp informacje o kontakcie zmiennymi zastępczymi szablonu, które aplikacja scali z wybranymi danymi.

Oto szablon przykładowego listu z obiektami zastępczymi, które można scalić z rzeczywistymi danymi ze źródła, takiego jak zwykły tekst lub Arkusze. Oto jak wygląda ten szablon:

Następnie za pomocą zmiennej SOURCE wybierz zwykły tekst lub Arkusze jako źródło danych. Domyślnie jest to zwykły tekst, co oznacza, że dane przykładowe używają zmiennej TEXT_SOURCE_DATA. Aby pobrać dane z Arkuszy, zmień zmienną SOURCE na 'sheets' i skieruj ją do naszego przykładowego arkusza (lub własnego), ustawiając zmienną SHEETS_FILE_ID.

Oto jak wygląda arkusz, aby można było zobaczyć format:

Wypróbuj aplikację z 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
  • Pobieranie danych ze źródła danych
  • Przechodzenie przez poszczególne wiersze danych
    • Utwórz kopię szablonu
    • Połącz kopię z danymi
    • Link wyjściowy do nowo scalonego dokumentu

Wszystkie nowo scalone listy pojawiają się też na Moim dysku użytkownika. Przykład scalonego dokumentu:

Kod źródłowy

Python

docs/mail-merge/docs_mail_merge.py
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.