일일 유지 관리를 위한 저장 프로시저

소개

|GAAD|는 데이터 수집 및 커넥터 구성을 프로그래밍 방식으로 관리할 수 있는 여러 저장 프로시저를 제공합니다. 다음은 사용법, 매개 변수, 예시를 포함한 각 저장 프로시저에 대한 자세한 설명입니다.

새 보고서 구성하기

CONFIGURE_REPORT 프로시저는 Google Analytics 4(GA4)에서 Snowflake로 데이터를 수집하기 위한 새 보고서를 구성합니다. 이 프로시저는 차원, 메트릭, 수집 일정 등 보고서의 매개 변수를 입력으로 사용합니다.

CALL CONFIGURE_REPORT( <report_name>, <property_id>, <dimensions>, <metrics>, <start_date>, <refresh_interval>[, <keep_empty_rows>][, <avoid_sampling>]);
Copy

여기서

report_name

구성할 보고서의 이름을 지정하는 문자열입니다. 이 이름은 대상 데이터베이스에서 생성된 원시 데이터가 있는 테이블의 접두사로 사용됩니다. 초기 수집 후 보고서 이름은 대상 데이터베이스에서 생성된 뷰의 이름으로 사용됩니다. 필수.

보고서 이름은 다음과 같아야 합니다.

  • 문자(대문자 또는 소문자) 또는 밑줄로 시작합니다.

  • 문자(대문자 또는 소문자), 숫자 또는 밑줄을 사용하여 하나 이상의 문자로 계속됩니다.

  • 150자 이하여야 합니다.

property_id

보고서에 사용할 Google Analytics 4 속성 ID를 지정하는 문자열입니다. 속성 ID는 GA4 계정에서 확보할 수 있는 숫자 형식을 갖습니다. PROPERTY_ID가 커넥터 인증 방법(oauth2 또는 서비스 계정)에서 액세스할 수 있는 GA4 속성에 해당하는지 확인합니다. 필수.

dimensions

보고서에 포함할 GA4 차원을 쉼표로 구분한 목록입니다. 차원은 쉼표로 구분해야 합니다. date 차원이 명시적으로 지정되지 않으면 자동으로 추가됩니다. 최대 9개의 차원을 지정할 수 있습니다(date 포함). 필수.

예: 'country,city,deviceCategory,sessions'

metrics

보고서에 포함할 GA4 메트릭을 쉼표로 구분한 목록입니다. 하나 이상의 메트릭이 필요하며 최대 10개의 메트릭을 지정할 수 있습니다. 필수.

예: 'sessions,pageViews'.

start_date

보고서의 시작 날짜를 지정하는 문자열입니다. 날짜는 YYYY-MM-DD 형식이어야 합니다. 이 날짜 이후의 데이터가 수집됩니다. 필수.

refresh_interval

보고서의 새로 고침 간격을 지정하는 문자열입니다. 필수 . 간격은 다음 형식 중 하나여야 합니다.

  • 'EVERY <분 단위 수> MINUTE'

  • 'EVERY <시간 단위 수> HOUR'

  • 'EVERY <일 단위 수> DAY'

keep_empty_rows

선택 사항입니다. 기본값은 false 입니다. ``true``인 경우 출력 테이블에는 모든 메트릭이 0인 차원 조합이 있는 레코드가 포함됩니다. 이벤트가 없는 차원 조합을 분석하는 데 유용합니다.

avoid_sampling

선택 사항입니다. 기본값은 false 입니다. ``true``인 경우 커넥터는 데이터 샘플링을 피하기 위해 GA4 API에서 데이터를 가져오는 방식을 조정할 수 있습니다. 데이터 정확도를 개선할 수 있지만 API 호출 빈도가 증가할 수 있습니다.

참고

데이터가 샘플링되지 않는다는 보장은 없습니다. 커넥터는 샘플링을 피하기 위해 노력하지만, 모든 경우에 가능한 것은 아닙니다. 이는 GA4 API의 제한 사항 때문입니다.

예:

CALL CONFIGURE_REPORT(
    REPORT_NAME => 'USER_ENGAGEMENT_REPORT',
    PROPERTY_ID => '123456789',
    DIMENSIONS => 'country,deviceCategory',
    METRICS => 'activeUsers,newUsers',
    START_DATE => '2023-01-01',
    REFRESH_INTERVAL => 'EVERY 1 DAY',
    KEEP_EMPTY_ROWS => TRUE,
    AVOID_SAMPLING => TRUE
);
Copy

기존 보고서 제거하기

DELETE_REPORT 프로시저는 커넥터에서 기존 보고서 구성을 삭제하여 해당 보고서에 대한 추가 데이터 수집을 중지합니다. 이미 수집된 데이터는 제거되지 않습니다.

CALL DELETE_REPORT( <report_name> );
Copy

여기서

report_name

삭제할 보고서의 이름을 지정하는 문자열입니다. CONFIGURE_REPORT에 사용된 REPORT_NAME과 일치해야 합니다. 필수.

예:

CALL DELETE_REPORT('USER_ENGAGEMENT_REPORT');
Copy

Google Analytics 4 계정의 목록 속성

GET_PROPERTIES 프로시저는 커넥터가 수집할 수 있는 모든 Google Analytics 4 속성의 목록을 반환합니다.

CALL GET_PROPERTIES();
Copy

프로시저의 출력 예:

{[
  { "propertyName": "test1", "propertyId": "1" },
  { "propertyName": "test2", "propertyId": "2" },
  { "propertyName": "test3", "propertyId": "3" }
]}
Copy

참고

커넥터에는 속성에 액세스하는 데 필요한 권한이 있어야 합니다. 결과가 비어 있으면 GA4에서 액세스 권한을 확인합니다.

GA4 속성에 대한 차원 및 메트릭 가져오기

GET_DIMENSIONS_AND_METRICS 프로시저는 지정된 GA4 속성에 대해 사용 가능한 차원 및 메트릭 목록을 검색합니다.

CALL GET_DIMENSIONS_AND_METRICS( <property_id> );
Copy

여기서

property_id

보고서에 사용할 Google Analytics 4 속성 ID를 지정하는 문자열입니다. 속성 ID는 GA4 계정에서 확보할 수 있는 숫자 형식을 갖습니다. ``property_id``가 커넥터 인증 방법(oauth2 또는 서비스 계정)에서 액세스할 수 있는 GA4 속성에 해당하는지 확인합니다. 필수.

예:

CALL GET_DIMENSIONS_AND_METRICS('123456789');
Copy

프로시저의 출력 예:

{
  "dimensions": [
    {
      "dimension": "achievementId", "category": "Other", "description": "Some description."
    }
  ],
  "metrics": [
    {
      "metric": "active1DayUsers", "category": "User", "description": "Some description."
    },
    {
      "metric": "active28DayUsers", "category": "User", "description": "Some description."
    }
  ]
}
Copy

참고

사용 가능한 차원과 메트릭은 속성마다 다를 수 있습니다.

커넥터 일시 중지하기

PAUSE_CONNECTOR 프로시저는 커넥터를 일시 중지하여 모든 데이터 수집 및 처리를 중지합니다.

CALL PAUSE_CONNECTOR();
Copy

참고

  • 커넥터를 일시 중지하면 구성된 모든 보고서의 데이터 수집이 중지됩니다.

  • RESUME_CONNECTOR를 사용하여 데이터 수집을 재개할 수 있습니다.

  • 일시 중지 중에도 기존 데이터에 계속 액세스할 수 있습니다.

커넥터 재개하기

RESUME_CONNECTOR 프로시저는 커넥터를 재개하여 이전에 일시 중지된 모든 데이터 수집 및 처리를 시작합니다. 데이터 수집은 일시 중지된 지점부터 계속됩니다.

CALL RESUME_CONNECTOR();
Copy

온디맨드 수집

INGEST_NOW 프로시저는 커넥터에서 지정된 보고서에 대한 데이터 수집을 예약합니다. 이 프로시저는 예약된 간격을 벗어나 특정 보고서에 대한 데이터 수집을 수동으로 시작하는 데 사용할 수 있습니다.

참고

프로시저는 ``EXECUTE TASK …``를 사용하여 지정된 보고서에 대한 즉각적인 수집을 예약합니다. 즉, 수집이 가능한 한 빨리 시작되지만, 특히 동일한 보고서에 대한 수집이 이미 진행 중인 경우 즉시 수집이 시작되지 않을 수 있습니다. 이 프로시저를 호출하기 전에 커넥터가 일시 중지되지 않았는지 확인합니다.

CALL INGEST_NOW('<report_name>');
Copy

여기서

report_name

수집할 보고서의 이름을 지정하는 문자열입니다. CONFIGURE_REPORT에 사용된 REPORT_NAME과 일치해야 합니다. 필수.

예:

CALL INGEST_NOW('USER_ENGAGEMENT_REPORT');
Copy

커넥터의 현재 상태 가져오기

참고

커넥터 state 및 커넥터 status``는 이 문서에서 서로 바꿔서 사용됩니다. 커넥터의 상태는 ``GET_CONNECTOR_STATUS 프로시저를 사용하여 검색할 수 있습니다.

CALL GET_CONNECTOR_STATUS();
Copy

프로시저의 출력 예:

{
  "response_code": "OK",
  "status": "STARTED",
  "configurationStatus": "PREREQUISITES_DONE"
}
Copy

이 프로시저는 다음 필드가 포함된 JSON 오브젝트를 반환합니다.

  • response_code - 프로시저가 성공적으로 실행된 경우 OK 값이 반환됩니다. OK 이외의 응답 코드는 오류를 나타냅니다.

  • status - 커넥터의 현재 상태입니다. 이 상태는 커넥터를 재설치 및 설치하거나, 일시 중지하거나, 재개하거나, 구성 프로세스를 완료할 때만 변경될 수 있습니다. 다음 값 중 하나를 가질 수 있습니다.

    • CONFIGURING - 목록 또는 애플리케이션 패키지에서 커넥터가 설치된 후 설정되는 기본 상태입니다. 커넥터는 구성 프로세스가 완료될 때까지 이 상태로 유지됩니다. 구성이 완료되면 커넥터가 STARTED 상태로 전환됩니다.

    • STARTED - 커넥터가 완전히 구성되거나 재개되면 STARTED 상태로 전환됩니다.

    • PAUSED - 커넥터가 일시 중지되면 PAUSED상태로 전환됩니다.

    • ERROR - 커넥터에 되돌릴 수 없는 오류가 발생하면 ERROR 상태로 전환되며, 이는 적극적으로 사용할 수 없음을 나타냅니다. 이 상태에 있을 때, RECOVER_CONNECTOR_STATE 프로시저는 유효한 상태로 전환하기 위해 사용될 수 있습니다.

  • configurationStatus - 기본 CONFIGURING 상태의 하위 상태입니다. 커넥터 구성 프로세스는 이 하위 상태에 따라 추적되는 몇 가지 단계로 나뉩니다. 다음 값 중 하나를 가질 수 있습니다.

    • INSTALLED - 커넥터 인스턴스가 생성된 후 INSTALLED 상태에서 구성이 시작됩니다.

    • PREREQUISITES_DONE - 사용자가 전제 조건을 완료하고 MARK_ALL_PREREQUISITES_AS_DONE 프로시저를 호출하면 구성이 PREREQUISITES_DONE 상태로 전환됩니다. 전제 조건은 사용자가 실행해야 하는 수동 단계입니다(예: 서드 파티 데이터 소스에 대한 연결 구성 또는 대상 데이터베이스 생성).

    • CONFIGURED - CONFIGURE_CONNECTOR(VARIANT) 프로시저가 호출된 상태입니다.

    • CONNECTED - SET_CONNECTION_CONFIGURATION(VARIANT) 프로시저가 호출된 상태입니다.

    • FINALIZED - 마지막으로, 구성을 완료하면 구성이 FINALIZED 상태(FINALIZE_CONNECTOR_CONFIGURATION(VARIANT) 프로시저가 호출됨)로 전환됩니다.

구성 프로세스 다시 시작하기

RESET_CONFIGURATION 저장 프로시저는 커넥터의 구성을 기본 상태로 재설정합니다. 이 프로시저는 구성이 완료되기 전에 커넥터의 구성을 재설정하는 데 사용될 수 있습니다. 프로시저가 작동하려면 커넥터가 CONFIGURING 상태여야 합니다. 커넥터 기본 상태 및 구성 하위 상태에 대한 자세한 내용은 커넥터의 현재 상태 가져오기 섹션을 참조하세요.

구성 단계가 완료된 경우(FINALIZED) 이 프로시저는 오류를 반환합니다.

CALL RESET_CONFIGURATION();
Copy

중간 상태 또는 오류 상태에서 복구하기

RECOVER_CONNECTOR_STATE 프로시저는 커넥터가 중간 상태 또는 오류 상태(ERROR, STARTING, PAUSING)에서 멈춰 있을 때 해당 상태를 수동으로 STARTED 또는 PAUSED 상태로 설정하여 커넥터를 복구하도록 설계되었습니다. 일부 작업에서는 커넥터가 일관되지 않은 상태로 남을 수 있으며, 이는 다양한 이유로 발생할 수 있습니다. 예를 들어, 사용자가 커넥터에 필요한 특정 데이터베이스 오브젝트에 대한 권한을 삭제하는 경우입니다.

새로운 상태가 유효하지 않거나 커넥터가 미리 지정된 상태 중 하나가 아닌 경우 프로시저는 오류를 반환합니다. 다음과 같은 전환이 허용됩니다.

  • ERROR -> PAUSED

  • ERROR -> STARTED

  • PAUSING -> PAUSED

  • PAUSING -> STARTED

  • STARTING -> PAUSED

  • STARTING -> STARTED

CALL RECOVER_CONNECTOR_STATE('<new_state>');
Copy

여기서

new_state

커넥터의 새로운 상태를 지정하는 문자열입니다. 상태는 STARTED 또는 PAUSED 중 하나여야 합니다. 필수.

예:

CALL RECOVER_CONNECTOR_STATE('STARTED');
Copy

커넥터가 삭제된 후 보고서 복구하기

IMPORT_STATE 프로시저는 커넥터가 제거된 후 구성된 보고서와 수집 기록을 복구하는 데 사용됩니다. 이 프로시저는 커넥터를 다시 설치하고 제거된 커넥터에서 사용한 데이터베이스와 동일한 데이터베이스를 사용하도록 새 커넥터를 구성한 후에 사용해야 합니다. 가져오는 상태는 커넥터의 이전 인스턴스에서 사용된 대상 데이터베이스에 SFSDKEXPORT 접미사가 있는 테이블 형태로 있습니다. 프로세스 대한 자세한 내용은 재해 복구 가이드를 참조하세요. force 매개 변수가 ``true``로 설정되지 않는 한, 프로시저는 해당 상태가 초기 상태가 아닌 것으로 감지되는 경우 커넥터의 기존 상태를 덮어쓰지 않습니다. 초기 상태는 구성 프로세스가 완료된 직후 보고서가 구성되지 않은 상태입니다. 보고서가 구성되었지만 나중에 삭제된 경우도 초기 상태가 아닌 것으로 간주됩니다.

참고

CASCADE 옵션으로 커넥터가 제거(삭제)된 경우 이 프로시저가 작동하지 않습니다.

CALL IMPORT_STATE([force]);
Copy

여기서

force

선택 사항입니다. 기본값은 false 입니다. ``true``인 경우 프로시저는 커넥터의 기존 상태를 덮어씁니다. 이미 구성된 모든 보고서를 포함합니다. ``false``인 경우 프로시저는 상태가 초기 상태가 아님을 감지하면 오류를 반환합니다.

예:

CALL IMPORT_STATE();
Copy
언어: 한국어