Apps Script 태스크

공지: 이제 Google Cloud 프로젝트에서 Application Integration을 사용할 수 있습니다. 이제 동일한 Google Cloud 프로젝트 내에서 Apigee Integration 및 Application Integration을 모두 사용할 수 있습니다. 자세히 알아보기

Apps Script 태스크를 사용하면 통합에서 Google Apps Script를 실행할 수 있습니다. Google Apps Script는 빠르고 쉽게 비즈니스 애플리케이션을 만들 수 있도록 하는 빠른 애플리케이션 개발 플랫폼입니다. 자세한 내용은 Google Apps Script를 참조하세요. 이 태스크는 커스텀 스크립트를 실행하거나 통합에서 기존 스크립트를 재사용하려는 경우에 유용합니다.

참고: Apps Script 태스크는 리전화되지 않은 전역 서비스입니다.

시작하기 전에

Apps Script 태스크를 사용하기 전에 다음 단계를 완료해야 합니다.

• AppsScript API 사용 설정
• OAuth 2.0 클라이언트 ID 만들기
• 인증 프로필 설정
• Google Cloud 프로젝트에서 Apigee Integration에 VPC 서비스 제어가 설정되지 않았는지 확인합니다.
  경고: Google Cloud 프로젝트에서 Apigee Integration에 VPC 서비스 제어가 설정된 경우 Cloud 함수가 작동하지 않거나 작동을 중지합니다.

AppsScript API 사용 설정

이 태스크를 사용하려면 Google Cloud 프로젝트와 AppsScript 사용자 계정에서 AppsScript API를 사용 설정해야 합니다. Google Cloud 프로젝트에서 AppsScript API 사용 설정에 대한 자세한 내용은 표준 Google Cloud 프로젝트에서 API 사용 설정을 참조하세요. 사용자 계정에서 API를 사용 설정하려면 설정을 클릭하고 Google Apps Script API를 On으로 설정합니다.

OAuth 2.0 클라이언트 ID 만들기

OAuth 2.0 클라이언트 ID를 사용할 수 있는 경우 이 단계를 건너뛰고 인증 프로필 설정으로 진행합니다.

새 OAuth 클라이언트 ID 만들기에 대한 자세한 내용은 OAuth 클라이언트 ID 만들기를 참조하세요.

인증 프로필 설정

Apigee Integration은 인증 프로필을 사용하여 Apps Script 프로젝트를 배포하고 실행하기 위해 Google Cloud에 연결합니다. 인증 프로필을 설정하려면 다음 단계를 수행하세요.

Apps Script 태스크 추가

1. Apigee UI에서 Apigee 조직을 선택합니다.
2. 개발 > 통합을 클릭합니다.
3. 기존 통합을 선택하거나 통합 만들기를 클릭하여 새 통합을 만듭니다.

   새 통합을 만드는 경우:

   1. 통합 만들기 대화상자에 이름과 설명을 입력합니다.
   2. 지원되는 리전 목록에서 통합에 대한 리전을 선택합니다.
   3. 만들기를 클릭합니다.

   통합 디자이너 페이지에서 통합이 열립니다.

4. 통합 설계자 탐색 메뉴에서 +태스크/트리거 추가 > 태스크를 클릭하여 사용 가능한 태스크 목록을 봅니다.
5. Apps Script 요소를 클릭하고 통합 편집기에 배치합니다.

인증 프로필 만들기

1. 디자이너에서 Apps Script 요소를 클릭하여 Apps Script 태스크 구성 창을 확인합니다.
2. Apps Script 태스크의 태스크 구성 창에서 +새 인증 프로필을 클릭합니다.
3. 인증 프로필 대화상자에서 프로필의 이름과 설명을 입력하고 다음 속성을 설정합니다.
   • 인증 유형: OAuth 2.0 승인 코드를 선택합니다.
   • 인증 엔드포인트: https://accounts.google.com/o/oauth2/auth를 입력합니다.
   • 토큰 엔드포인트: https://oauth2.googleapis.com/token을 입력합니다.
   • 클라이언트 ID: 클라이언트 ID를 입력합니다.

     Google Cloud 프로젝트 대시보드의 사용자 인증 정보 > OAuth 2.0 클라이언트 ID에서 클라이언트 ID를 확인할 수 있습니다.

   • 보안 비밀: 클라이언트 보안 비밀번호를 입력합니다.

     Google Cloud 프로젝트 대시보드의 사용자 인증 정보 > OAuth 2.0 클라이언트 ID에서 클라이언트 보안 비밀번호를 확인할 수 있습니다.

   • 범위: 다음을 입력합니다.

     https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

     참고: 여러 범위를 공백 문자(' ')로 구분할 수 있습니다.

4. 액세스 토큰 생성 및 저장을 클릭합니다.

   승인 화면으로 리디렉션됩니다. 로그인하고 화면에 표시된 권한에 동의하여 액세스 토큰을 생성합니다. 액세스 토큰 생성에 성공하면 인증 프로필이 저장되고 통합을 계속 수정할 수 있습니다.

참고: 동일한 사용자가 인증 프로필을 만들고 Apps Script를 배포해야 합니다. 사용자가 다르면 Apps Script가 실행되지 않습니다.

Apps Script 태스크 구성

Apps Script 태스크에서 Apps Script 프로젝트를 구성하려면 다음 단계를 수행합니다.

1. 태스크 구성 창에서 Apps Script 프로젝트 구성을 클릭합니다.

   Apps Script 구성 대화상자가 표시됩니다.

2. 기존 Apps Script 프로젝트에 연결하거나 새 Apps Script 프로젝트를 만들 수 있습니다.

   Apps Script 프로젝트를 구성하면 Apps Script 프로젝트가 Apigee Integration의 통합과 연결됩니다.

3. 저장을 클릭합니다.
4. Apps Script 프로젝트 열기를 클릭합니다.

   Apps Script 편집기에서 다음 파일을 볼 수 있습니다.

   • Run.gs: 실행 가능한 코드를 포함합니다. run 함수 내에서 스크립트를 작성합니다. 이 함수는 Apps Script 태스크가 실행될 때 호출됩니다. 통합 수준에서 정의된 변수를 스크립트에 사용할 수 있습니다. 통합 변수 사용에 대한 자세한 내용은 통합 변수 사용을 참조하세요.
   • Main.gs: 통합에서 Apps Script를 실행하는 초기화 코드를 포함합니다. 이 파일을 수정하거나 수정하지 마세요.
   • Test.gs: 테스트를 실행할 수 있는 실행 코드를 포함합니다. testRun 함수 내에 스크립트를 작성하여 스크립트를 테스트할 수 있습니다.

   프로젝트를 웹 앱 형식으로 배포해야 합니다. 다양한 배포 모드에 대한 자세한 내용은 배포 만들기 및 관리를 참조하세요.

통합 변수에 액세스

Apps Script 태스크는 스크립트에서 통합 변수를 사용할 수 있게 해주는 AppsScriptTask 라이브러리를 사용합니다. AppsScriptTask 라이브러리는 자동으로 가져오기되며 run 함수에서 사용할 수 있습니다.

Apps Script에서 통합 변수에 액세스하려면 변수를 태스크 매개변수 형태로 Apps Script 태스크에 전달해야 합니다. 태스크 매개변수는 키-값 쌍입니다. 여기서 키는 AppsScript 작업의 변수 이름이고 값은 해당 통합 변수 이름입니다. 태스크 구성 창의 태스크 매개변수 섹션에서 태스크를 하나 이상 추가할 수 있습니다.

예를 들어 Apps Script에서 사용하려는 Product라는 통합 변수가 있는 경우 키를 ProductKey로 정의하고 값을 Product로 정의할 수 있습니다. 그러면 Apps Script에서 AppsScriptTask.getTaskParameter('ProductKey')을 사용하여 Product 변수를 읽을 수 있습니다.

참고: AppsScript에서 통합 변수를 사용하려면 변수를 Apps Script 태스크에 태스크 매개변수로 추가해야 합니다.

AppsScriptTask 라이브러리는 통합 변수에 액세스할 수 있는 다음과 같은 메서드를 제공합니다.

• setIntegrationVariable
• getTaskParameter

함수 이름	설명	용도
setIntegrationVariable	제공된 값을 변수로 설정합니다.	구문: setIntegrationVariable(value,value) 예: // Write to an Integer variable AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');
getTaskParameter	변수 값을 가져옵니다.	구문: getTaskParameter(value) 예: // Read an integration variable AppsScriptTask.getTaskParameter('EmployeeIDKey');

AppsScriptTask 라이브러리에서 사용 가능한 모든 함수를 보려면 Apps Script 편집기에서 AppsScriptTask 메뉴 항목 위로 마우스를 가져간 다음 더보기 > 새 탭에서 열기를 클릭합니다.

Apps Script 테스트

통합을 게시하기 전에 Test.gs 파일에서 제공하는 testRun 함수를 사용하여 스크립트를 테스트할 수 있습니다. AppsScriptTaskTest 라이브러리를 사용하여 testRun 함수에 테스트 코드를 작성합니다. 이 라이브러리를 사용하면 어설션 기반 테스트 사례를 실행할 수 있으며 testRun 함수에서 사용할 수 있도록 자동으로 가져옵니다.

AppsScriptTaskTest 라이브러리에서 사용 가능한 모든 함수를 보려면 Apps Script 편집기에서 AppsScriptTaskTest 메뉴 항목 위로 마우스를 가져간 다음 더보기 > 새 탭에서 열기를 클릭합니다.

다음 샘플은 AppsScriptTaskTest 라이브러리 함수의 사용법을 보여줍니다.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

다음 샘플에서는 testRun 메서드에서 JSON 및 배열 변수에 액세스하는 방법을 보여줍니다.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);

  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

테스트 사례를 실행한 후 실행 로그에서 어설션을 볼 수 있습니다. 로그를 보려면 메뉴에서 실행 로그를 클릭합니다.

권장사항

통합의 태스크에 1~2초 미만의 지연 시간이 필요한 경우 Apps Script 태스크를 사용하지 않는 것이 좋습니다.

또한 성능 병목 현상을 최소화하기 위해서는 여러 Apps Script 태스크를 연결하는 대신 단일 Apps Script 태스크에서 모든 로직을 코딩하는 것이 좋습니다.

Apps Script 태스크에 적용되는 사용량 한도에 대한 자세한 내용은 사용량 한도를 참조하세요.

고려사항

Apps Script 태스크를 통합 설계에 포함할 경우 다음과 같은 시스템 제한사항을 고려하세요.

• AppsScript의 최대 활성 배포 수: 50
• API 실행의 초당 쿼리 수(QPS): 5,000/분
• 웹 앱 배포의 초당 쿼리 수(QPS): 5000/분
• API 실행 지연 시간: 1.5초
• 웹 앱 지연 시간: 2.5초
• AppsScript의 모든 통합 변수 최대 누적 크기: 15MB

오류 처리 전략

태스크의 오류 처리 전략은 일시적인 오류로 인해 태스크가 실패할 경우 수행할 태스크를 지정합니다. 오류 처리 전략을 사용하는 방법과 다양한 유형의 오류 처리 전략에 대한 자세한 내용은 오류 처리 전략을 참조하세요.