Adobe 문서 생성 API 실천

이번 주 Adobe는 announce를 Adobe 문서 서비스의 일부로 제공하는 것을 자랑스럽게 생각합니다Document Generation API.이것은 개발자가 템플릿과 동적 데이터로부터 Word와 PDF 문서를 생성할 수 있도록 하는 강력한 새로운 서비스이다.이 새로운 API는 Java, .Net, NodeSDK의 완전한 지원을 받아 REST API를 통해 다른 언어에서 사용할 수 있다.그것이 어떻게 일을 하는지 우리에게 보여 주시오.
문서 생성은 템플릿 역할을 하는 Word 문서를 데이터와 조합하여 이루어집니다.이러한 데이터는 JSON 파일로 하드코딩하거나 다른 API에서 동적으로 가져올 수 있습니다.Adobe 문서 생성 API는 Word 문서 템플릿을 가져오고 데이터를 입력한 다음 Word 문서 또는 PDF를 결과로 내보냅니다.간단한 프레젠테이션 어때요?
Word 문서부터 시작하겠습니다.Microsoft Word를 시작하고 약간의 타자 및 스타일 설정을 수행하여 제목과 짧은 텍스트 문장을 만들었습니다.

템플릿으로 만들기 위해서, 우리는 태그를 삽입해야 합니다. 이 태그들은 생성 과정에서 우리의 데이터로 대체됩니다.이러한 태그는 단순 변수 대체(데이터에 값을 삽입) 또는 조건과 순환을 포함한 더 복잡한 조작일 수 있다.Excel의 방정식과 유사한 표현식도 포함할 수 있습니다.
문서에 이러한 표현식을 추가할 수 있는 두 가지 방법이 있습니다.하나는 간단한 수작업이다.개발자에게는 가장 간단한 해결 방안일 수도 있다.(나에게 있어서 이것은 Liquid 템플릿 언어를 떠올리게 한다.)
다른 방법은 Adobe Document Generation Tagger "add-in"를 Microsoft Word에 설치하는 것입니다.내가 워드를 사용한 지 수십 년이 되었을지도 모르지만, 이것은 내가 단추보다 더 재미있는 것을 추가한 것을 처음 본 것이다.외부 프로그램은 정확한 태그를 삽입하는 것을 더욱 간단하게 하기 위해 편집기에 상호작용 편집기를 추가했다.
우리의 첫 번째 시연은 매우 간단할 것이기 때문에 우리는 수동 방식(알라바마, 오르막, 양방향, 눈밭에서)을 채택할 것이다.이름 표시자를 추가하기 위해 Word 문서를 편집합니다.

위의 화면 캡처에서 두 개의 영패가 모두 괄호를 사용한 것을 볼 수 있습니다: {{name}}.현재 우리는 생성 서비스와 함께 사용할 수 있는Word 문서를 가지고 있다.템플릿을 기반으로 새 Word 문서를 만드는 간단한 노드 스크립트를 보여 줍니다.(이하 코드는 Dellquick start에 기반하고 있으므로 다른 언어의 예제를 확인하십시오.)

const PDFToolsSdk = require('@adobe/documentservices-pdftools-node-sdk');
const fs = require('fs');

const inputFile = './hello1.docx';
const outputFile = './helloWorld.docx';

const data = {
    name: "Raymond Camden"
};

//remove output if exists
if(fs.existsSync(outputFile)) fs.unlinkSync(outputFile);

// Initial setup, create credentials instance.
const credentials =  PDFToolsSdk.Credentials
      .serviceAccountCredentialsBuilder()
      .fromFile("pdftools-api-credentials.json")
      .build();


// Create an ExecutionContext using credentials.
const executionContext = PDFToolsSdk.ExecutionContext.create(credentials);

// Create a new DocumentMerge options instance.
const documentMerge = PDFToolsSdk.DocumentMerge,
      documentMergeOptions = documentMerge.options,
      options = new documentMergeOptions.DocumentMergeOptions(data, documentMergeOptions.OutputFormat.DOCX);

// Create a new operation instance using the options instance.
const documentMergeOperation = documentMerge.Operation.createNew(options);

// Set operation input document template from a source file.
const input = PDFToolsSdk.FileRef.createFromLocalFile(inputFile);
documentMergeOperation.setInput(input);

// Execute the operation and Save the result to the specified location.
documentMergeOperation.execute(executionContext)
.then(result => result.saveAsFile(outputFile))
.catch(err => {
    if(err instanceof PDFToolsSdk.Error.ServiceApiError
        || err instanceof PDFToolsSdk.Error.ServiceUsageError) {
        console.log('Exception encountered while executing operation', err);
    } else {
        console.log('Exception encountered while executing operation', err);
    }
});

이 스크립트는 Adobe PDF Tools SDK를 포함하여 필요한 라이브러리에 먼저 로드됩니다.그런 다음 가져오기 및 내보내기 파일을 정의합니다.다음은 내 데이터로 정의할게.이것은 상대적으로 간단하지만, 파일 시스템에서 불러오거나 API 호출을 통해 얻을 수 있다.
템플릿의 나머지 부분은 우리Quick Start에서 왔지만 결국은 설정credentials으로 우리가 원하는 생성 유형(Word)을 정의하고 작업을 수행하는 것이다.
실행하면 새 단어 doc를 얻을 수 있습니다:

PDF 지원은 어떻습니까?출력 파일의 이름을 간단하게 변경할 수 있습니다.

const outputFile = './helloWorld.pdf';

변경options:

options = new documentMergeOptions.DocumentMergeOptions(data, documentMergeOptions.OutputFormat.PDF);

일단 달리기를 하면 우리는 다음과 같이 할 수 있다.

위의 스크립트 및 소스 Word 문서는 GitHub repo에서 찾을 수 있습니다.https://github.com/cfjedimaster/document-services-demos/tree/main/docgen
좋아, 우리 좀 더 복잡한 데이터로 그것을 한 단계 높여 보자.한 수의 진료소가 고객을 위해 문서를 만들어야 한다고 상상해 보세요.이 문서들은 고객과 동물에 대한 정보를 포함할 것이다.유일하게 적합한 애완동물은 고양이이기 때문에, 우리는 그들이 고양이를 가지고 있다고 가정한다.다음은 내 데이터 모양새입니다.

{
    "name":"Raymond Camden",
    "email":"[email protected]",
    "address":"1313 Mockingbird Lane, Lafayette, LA",
    "cell":"337-555-5555",
    "cats":[
        {"name":"Luna", "gender": "female", "breed": "something", "weight": 4},
        {"name":"Pig", "gender": "female", "breed": "something else", "weight": 8},
        {"name":"Cracker", "gender": "male", "breed": "large", "weight": 10}
    ]
}

우리는 맨 위에 기본적인 고객 정보(이름, 이메일, 주소와 핸드폰 번호)가 있고, 그 다음에 고양이 한 마리가 있는데, 고양이마다 이름, 성별, 품종과 체중이 있다.다음과 같은 기능을 가진 문서를 만들고자 합니다.

맨 위에 고객의 이름을 표시하고 가능한 한 많은 정보를 표시합니다.예를 들어 모든 고객 기록에 주소가 있는 것은 아니다.우리는 조건 라벨을 사용할 수 있다.

고양이의 이름, 성별, 품종을 보여 주는 표를 보여 준다.

무게를 초과한 고양이의 목록을 선택할 수 있습니다.

이것은 우리가 처음 보여준 것보다 좀 복잡하기 때문에, 지금은 템플릿을 사용하는 데 도움을 줄 수 있는 좋은 시기이다.먼저 정적 값으로 템플릿을 만듭니다.

외부 프로그램이 이미 설치되어 있는 경우 위쪽 리본에 표시되어야 합니다.

이 버튼을 클릭하면 문서 오른쪽에 새 패널이 열립니다.

시작을 클릭하면 JSON을 붙여넣거나 JSON 파일을 업로드하라는 메시지가 표시됩니다.

예시 데이터를 요구합니다.우리가 상상하는 응용 프로그램에서 당신은 우리의 고객과 애완동물 데이터가 데이터베이스에 저장되는 것을 상상할 수 있습니다.템플릿 구축을 시작하려면 템플릿을 설계하는 데 도움이 될 수 있도록 최소한 하나의 JSON 파일을 생성하거나 출력 데이터를 출력해야 할 수도 있습니다.나는 앞의 예에서 JSON 데이터를 사용했다.

Generate Tags 를 클릭하면 외부 프로그램에서 토큰을 삽입할 수 있습니다.기본 탭과 고급 탭 두 개가 있습니다.

간단한 데이터를 추가하는 것부터 시작합시다.Word 문서에서 기본 텍스트Jane Smith를 선택했고 외부 프로그램 패널에서 name를 선택한 다음 [텍스트 삽입] 단추를 눌렀다.이렇게 하면 기본 텍스트가 태그로 바뀝니다.

간단하죠?나는 이어서 이메일, 주소, 휴대전화를 바꾸었다.

그럼 집 전화번호는요?위에서 말한 바와 같이, 우리는 일부 고객들이 가정 번호가 없을 것이라고 예상한다. (우리의 테스트 데이터는 없다.)어떤 사람들은 휴대전화가 없을 수도 있다.다행히도 우리는 템플릿에 조건을 추가할 수 있다.
나는 먼저 휴대전화로 전체 회선을 선택한 후에 고급 옵션 카드로 전환했다.조건 컨텐트 섹션을 확장할 수 있습니다.

레코드 선택에서 드롭다운 목록을 입력하거나 사용할 수 있습니다.나는 '단원' 을 선택한 다음 '존재한다면' 단추를 눌렀다.이어서 나는 삽입 조건을 눌렀다.
{% conditional-section cell %} 라벨은 우리의 전체 줄을 포장하고 cell가 존재할 때만 최종 결과에 나타난다.우리는 가정 전화번호의 값이 없지만, 우리는 수동으로 같은 라벨을 복사하고 붙일 수 있다.(만약 내가 비기술 사용자와 함께 구축한다면 외부 프로그램이 그것을 가능성으로 간주할 수 있도록 빈 값을 제공할 것이다.)만약 고객이 가정 번호가 있다면, 그것은 homenumber라는 값으로 제공될 것이라고 가정합니다.
다음은 저희 템플릿 상단의 최종 버전입니다.

이제 우리 고양이 리스트를 추가합시다.여전히 외부 프로그램의 고급 부분에서 테이블과 목록에 들어갑니다.기본적으로 테이블은 선택되어 있습니다.우선 교체할 그룹 데이터를 선택해야 한다.외부 프로그램은 사용자의 데이터를 볼 수 있고 cats이 유일한 그룹이라는 것을 깨달을 수 있기 때문에'표 기록'드롭다운 목록의 유일한 옵션입니다.다음은 사용할 열을 지정해야 합니다."Select column records"를 입력하기 시작하면, 외부 프로그램은 다시 한 번 스마트합니다. 그룹에서 찾을 수 있는 키만 제안할 수 있습니다.나는 성명, 품종, 성별을 입력했다.

이번에 우리는 기존의 시계를 선택할 생각은 없다.반대로, 나는 커서가 표 뒤에 있는 것을 확인하고, '표 삽입' 을 눌렀다.

보시다시피, 제목이 있는 새 표를 만들었습니다.이제 우리는 새 테이블을 편집해서 이전에 사용했던 형식 (간단한 굵기와 가운데) 을 다시 적용하기만 하면 된다.나는 또 모든 열명 앞의'Cat'을 모두 없앴다. 왜냐하면 이것은 쓸데없는 것이기 때문이다.

이것은 외부 프로그램이 탭을 간단하게 추가하는 방법을 설명하는 좋은 예이지만, 완성된 후에도 청소, 스타일 설정 등을 해야 할 수도 있습니다.
마지막 특징은 무게를 초과할 수 있는 고양이를 열거한 것이다.이렇게 하려면 수동 편집으로 다시 전환합니다.나는 약간의 논리로 밑에 있는 목록을 수정했다.

내가 어떻게 알았지?우리의 문서 생성 논리는 JSONata를 사용하여 영패 해석을 하는데 나는 그들의 사이트에서 그들의 문서를 보는 데 시간이 좀 걸렸다.이것은 매력적인 시스템으로 약간의 시도와 오류가 필요할 수도 있지만, 너는 그것의 요령을 빨리 파악할 수 있다.
템플릿이 완성된 후에, 나는 새 발을 만들어서 그것을 사용하고 데이터를 불러왔다.이것은 이전 스크립트에 대한 경미한 수정이기 때문에, 다음은 내가 변경한 모든 내용입니다.

const inputFile = './catTemplate.docx';
const outputFile = './catCustomer.pdf';

const data = require('./catowner.json');

마찬가지로 이 값은 일반적으로 API 또는 데이터베이스 호출을 통해 로드됩니다.my GitHub repo 에서 전체 파일을 찾을 수 있습니다.다음은 아름다운 동적 결과입니다.

다음 단계

새 문서 생성 API에 대해 흥미로운 내용을 소개하시기 바랍니다.이것과 우리의 Adobe PDF Tools API를 등록해서 6개월 동안 무료로 시험해 볼 수 있다는 것을 명심하세요.또한 저희 docs를 꼭 확인해 주시고 문제가 있으면 forums로 가십시오.