ادغام نامه، ادغام نامه

این راهنما نحوه استفاده از Google Docs API را برای ادغام ایمیل توضیح می دهد.

معرفی

ادغام نامه مقادیری را از ردیف های یک صفحه گسترده یا منبع داده دیگری می گیرد و آنها را در یک سند الگو قرار می دهد. این به شما امکان می‌دهد یک سند اصلی (الگو) ایجاد کنید که از آن می‌توانید اسناد مشابه زیادی را ایجاد کنید که هر کدام با داده‌های در حال ادغام سفارشی شده‌اند. نتیجه لزوماً برای نامه‌های پستی یا فرم استفاده نمی‌شود، اما می‌تواند برای هر هدفی باشد، مانند ایجاد دسته‌ای از فاکتورهای مشتری.

ادغام ایمیل از زمانی که صفحات گسترده و پردازشگرهای کلمه وجود داشته است وجود داشته است و امروزه بخشی از گردش کار بسیاری از مشاغل است. قرارداد این است که داده ها را به عنوان یک رکورد در هر ردیف سازماندهی کند، با ستون هایی که فیلدهای موجود در داده ها را نشان می دهد، همانطور که در جدول زیر نشان داده شده است:

نام نشانی منطقه
1 UrbanPq خیابان 123 غرب
2 پاوکسانا خیابان دوم 456 جنوب

برنامه نمونه در این صفحه نشان می‌دهد که چگونه می‌توانید از Google Docs، Sheets، و APIهای Drive برای انتزاع جزئیات نحوه ادغام نامه‌ها استفاده کنید و از کاربران در برابر نگرانی‌های پیاده‌سازی محافظت کنید. اطلاعات بیشتر در مورد این نمونه پایتون را می‌توانید در مخزن GitHub نمونه پیدا کنید.

نمونه برنامه

این برنامه نمونه الگوی اصلی شما را کپی می کند و سپس متغیرها را از منبع داده تعیین شده شما در هر یک از کپی ها ادغام می کند. برای امتحان این نمونه برنامه، ابتدا الگوی خود را تنظیم کنید:

  1. یک فایل Docs ایجاد کنید . الگویی را که می خواهید استفاده کنید انتخاب کنید.
  2. به شناسه سند فایل جدید توجه کنید. برای اطلاعات بیشتر، به شناسه سند مراجعه کنید.
  3. متغیر DOCS_FILE_ID را روی شناسه سند تنظیم کنید.
  4. اطلاعات تماس را با متغیرهای نگهدارنده الگو جایگزین کنید که برنامه با داده های انتخابی ادغام می شود.

در اینجا یک الگوی نامه نمونه با متغیرهایی است که می تواند با داده های واقعی از منبعی مانند متن ساده یا Sheets ادغام شود. در اینجا شکل ظاهری آن الگو به شرح زیر است:

سپس، متن ساده یا Sheets را به عنوان منبع داده خود با استفاده از متغیر SOURCE انتخاب کنید. نمونه پیش‌فرض متن ساده است، به این معنی که داده‌های نمونه از متغیر TEXT_SOURCE_DATA استفاده می‌کنند. برای منبع داده‌ها از Sheets، متغیر SOURCE را به 'sheets' به‌روزرسانی کنید و با تنظیم متغیر SHEETS_FILE_ID آن را به برگه نمونه ما (یا خودتان) نشان دهید.

شکل ظاهری برگه به ​​این صورت است تا بتوانید قالب آن را ببینید:

برنامه را با داده های نمونه ما امتحان کنید، سپس آن را با داده ها و مورد استفاده خود تطبیق دهید. برنامه خط فرمان به صورت زیر عمل می کند:

  • برپایی
  • داده ها را از منبع داده واکشی کنید
  • از طریق هر ردیف داده حلقه بزنید
    • یک کپی از الگو ایجاد کنید
    • کپی را با داده ها ادغام کنید
    • پیوند خروجی به سند تازه ادغام شده

همه حروف تازه ادغام شده نیز در My Drive کاربر نشان داده می شود. نمونه ای از یک حرف ادغام شده چیزی شبیه به این است:

کد منبع

پایتون

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))
    )

برای اطلاعات بیشتر، فایل README و کد منبع کامل برنامه را در مخزن GitHub نمونه برنامه ببینید.