문서에 텍스트 병합

Google Docs API의 유용한 애플리케이션 중 하나는 하나 이상의 데이터 소스의 정보를 문서로 병합하는 것입니다.

이 페이지에서는 외부 소스의 데이터를 가져와 기존 템플릿 문서에 삽입하는 방법을 설명합니다.

템플릿 은 템플릿에서 생성된 모든 문서에 동일한 고정 텍스트가 포함된 특수한 유형의 문서로, 다른 동적 텍스트를 배치할 수 있는 지정된 자리표시자가 함께 포함되어 있습니다. 예를 들어 계약 템플릿에는 고정 콘텐츠와 함께 수신자의 이름, 주소, 기타 세부정보를 입력할 수 있는 공간이 있을 수 있습니다. 그러면 앱에서 고객별 데이터를 템플릿에 병합하여 완성된 문서를 만들 수 있습니다.

이 접근 방식이 유용한 이유는 다음과 같습니다.

  • 디자이너는 Google Docs 편집기를 사용하여 문서 디자인을 쉽게 미세 조정할 수 있습니다. 렌더링된 레이아웃을 설정하기 위해 앱에서 매개변수를 조정하는 것보다 훨씬 쉽습니다.

  • 콘텐츠와 프레젠테이션을 분리하는 것은 많은 이점이 있는 잘 알려진 디자인 원칙입니다.

병합의 개념 다이어그램

기본 레시피

다음은 Docs API를 사용하여 데이터를 문서에 병합하는 방법의 예입니다.

  1. 자리표시자 콘텐츠를 사용하여 디자인 및 형식에 도움이 되는 문서를 만듭니다. 바꾸려는 텍스트 서식은 유지됩니다.

  2. 삽입할 각 요소에 대해 자리표시자 콘텐츠를 태그로 바꿉니다. 일반적으로 발생하지 않을 문자열을 사용해야 합니다. 예를 들어 {{account-holder-name}}은 좋은 태그일 수 있습니다.

  3. 코드에서 Google Drive API를 사용하여 문서 사본을 만듭니다.

  4. 코드에서 문서 이름과 함께 Docs API's batchUpdate() 메서드를 사용하고 ReplaceAllTextRequest를 포함합니다.

문서 ID는 문서를 참조하며 URL에서 파생될 수 있습니다.

https://docs.google.com/document/d/DOCUMENT_ID/edit

예

다음 예에서는 템플릿의 모든 탭에서 2개의 필드를 실제 값으로 바꿔 완성된 문서를 생성합니다.

이 병합을 실행하려면 아래 코드를 사용하면 됩니다.

자바

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

List 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(DOCUMENT_ID, 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()

템플릿 관리

애플리케이션이 정의하고 소유하는 템플릿 문서의 경우 애플리케이션을 나타내는 전용 계정을 사용하여 템플릿을 만듭니다. 서비스 계정 은 좋은 선택이며 공유를 제한하는 Google Workspace 정책과 관련된 복잡한 문제를 방지합니다.

템플릿에서 문서 인스턴스를 만들 때는 항상 최종 사용자 사용자 인증 정보를 사용하세요. 이렇게 하면 사용자가 결과 문서를 완전히 제어할 수 있으며 Drive의 사용자별 한도와 관련된 확장 문제를 방지할 수 있습니다.

서비스 계정을 사용하여 템플릿을 만들려면 애플리케이션 사용자 인증 정보로 다음 단계를 실행하세요.

  1. Docs API에서 documents.create 를 사용하여 문서를 만듭니다.
  2. Drive API에서 permissions.create 를 사용하여 문서 수신자가 문서를 읽을 수 있도록 권한을 업데이트합니다.
  3. Drive API에서 permissions.create 를 사용하여 템플릿 작성자가 문서를 작성할 수 있도록 권한을 업데이트합니다.
  4. 필요에 따라 템플릿을 수정합니다.

문서 인스턴스를 만들려면 사용자 사용자 인증 정보로 다음 단계를 실행하세요.

  1. Drive API에서 files.copy를 사용하여 템플릿 사본을 만듭니다.
  2. Docs API에서 documents.batchUpdate 를 사용하여 값을 바꿉니다.