문서에 텍스트 병합

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

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

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

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

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

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

병합의 개념 다이어그램

기본 레시피

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

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

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

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

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

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

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

예

템플릿의 모든 탭에서 2개의 필드를 실제 값으로 대체하여 완성된 문서를 생성하는 다음 예시를 참고하세요.

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

자바

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

템플릿 관리

애플리케이션이 정의하고 소유하는 템플릿 문서의 경우 애플리케이션을 나타내는 전용 계정을 사용하여 템플릿을 만듭니다. 서비스 계정을 사용하면 공유를 제한하는 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를 사용하여 값을 바꿉니다.