작업 스케줄링

• 소개
• 스케줄 정의
  • Artisan 명령어 스케줄링
  • 큐에 넣은 작업 스케줄링
  • 쉘 명령어 스케줄링
  • 스케줄 빈도 옵션
  • 시간대
  • 작업 중복 방지
  • 한 서버에서만 작업 실행
  • 백그라운드 작업
  • 유지보수 모드
  • 스케줄 그룹
• 스케줄러 실행
  • 분 이하로 스케줄링된 작업
  • 로컬에서 스케줄러 실행
• 작업 출력
• 작업 후크
• 이벤트

소개

과거에는 서버에서 스케줄링해야 하는 각 작업에 대해 cron 구성 항목을 작성했을 수 있습니다. 그러나 이렇게 하면 작업 스케줄이 더 이상 소스 제어에 있지 않고 기존 cron 항목을 보거나 추가 항목을 추가하려면 서버에 SSH로 접속해야 하므로 빠르게 문제가 될 수 있습니다.

Laravel의 명령 스케줄러는 서버에서 스케줄링된 작업을 관리하는 새로운 접근 방식을 제공합니다. 스케줄러를 사용하면 Laravel 애플리케이션 내에서 명령 스케줄을 유연하고 표현적으로 정의할 수 있습니다. 스케줄러를 사용할 때는 서버에 단일 cron 항목만 필요합니다. 작업 스케줄은 일반적으로 애플리케이션의 routes/console.php 파일에 정의됩니다.

스케줄 정의

애플리케이션의 routes/console.php 파일에서 스케줄링된 모든 작업을 정의할 수 있습니다. 시작하려면 예제를 살펴보겠습니다. 이 예제에서는 매일 자정에 호출되도록 클로저를 스케줄링합니다. 클로저 내에서 테이블을 지우기 위해 데이터베이스 쿼리를 실행합니다.

<?php
 
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schedule;
 
Schedule::call(function () {
    DB::table('recent_users')->delete();
})->daily();

클로저를 사용하여 스케줄링하는 것 외에도 호출 가능한 객체를 스케줄링할 수도 있습니다. 호출 가능한 객체는 __invoke 메서드를 포함하는 간단한 PHP 클래스입니다.

Schedule::call(new DeleteRecentUsers)->daily();

routes/console.php 파일을 명령 정의 전용으로 예약하려는 경우, 애플리케이션의 bootstrap/app.php 파일에서 withSchedule 메서드를 사용하여 스케줄링된 작업을 정의할 수 있습니다. 이 메서드는 스케줄러의 인스턴스를 받는 클로저를 허용합니다.

use Illuminate\Console\Scheduling\Schedule;
 
->withSchedule(function (Schedule $schedule) {
    $schedule->call(new DeleteRecentUsers)->daily();
})

스케줄링된 작업의 개요와 다음에 실행되도록 스케줄링된 시간을 보려면 schedule:list Artisan 명령어를 사용할 수 있습니다.

php artisan schedule:list

Artisan 명령어 스케줄링

클로저를 스케줄링하는 것 외에도 Artisan 명령어와 시스템 명령어를 스케줄링할 수도 있습니다. 예를 들어, command 메소드를 사용하여 명령어 이름 또는 클래스를 사용하여 Artisan 명령어를 스케줄링할 수 있습니다.

명령어 클래스 이름을 사용하여 Artisan 명령어를 스케줄링할 때, 호출 시 명령어에 제공해야 할 추가적인 명령줄 인수의 배열을 전달할 수 있습니다:

use App\Console\Commands\SendEmailsCommand;
use Illuminate\Support\Facades\Schedule;
 
Schedule::command('emails:send Taylor --force')->daily();
 
Schedule::command(SendEmailsCommand::class, ['Taylor', '--force'])->daily();

Artisan 클로저 명령어 스케줄링

클로저로 정의된 Artisan 명령어를 스케줄링하려면 명령어 정의 뒤에 스케줄링 관련 메소드를 연결할 수 있습니다:

Artisan::command('delete:recent-users', function () {
    DB::table('recent_users')->delete();
})->purpose('Delete recent users')->daily();

클로저 명령어에 인수를 전달해야 하는 경우, schedule 메소드에 인수를 제공할 수 있습니다:

Artisan::command('emails:send {user} {--force}', function ($user) {
    // ...
})->purpose('Send emails to the specified user')->schedule(['Taylor', '--force'])->daily();

큐 작업 스케줄링

job 메소드를 사용하여 큐 작업을 스케줄링할 수 있습니다. 이 메소드는 작업을 큐에 넣기 위해 call 메소드를 사용하여 클로저를 정의하지 않고도 큐 작업을 스케줄링하는 편리한 방법을 제공합니다:

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;
 
Schedule::job(new Heartbeat)->everyFiveMinutes();

선택적으로 job 메소드에 두 번째 및 세 번째 인수를 제공할 수 있으며, 이는 작업을 큐에 넣는 데 사용해야 하는 큐 이름과 큐 연결을 지정합니다:

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;
 
// "sqs" 연결의 "heartbeats" 큐에 작업 디스패치...
Schedule::job(new Heartbeat, 'heartbeats', 'sqs')->everyFiveMinutes();

쉘 명령어 스케줄링

exec 메소드를 사용하여 운영 체제에 명령어를 실행할 수 있습니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::exec('node /home/forge/script.js')->daily();

스케줄 빈도 옵션

지정된 간격으로 작업을 실행하도록 구성하는 방법의 몇 가지 예시를 이미 보았습니다. 그러나 작업에 할당할 수 있는 더 많은 작업 스케줄 빈도가 있습니다:

이러한 메소드는 추가적인 제약 조건과 결합하여 특정 요일에만 실행되는 훨씬 더 미세 조정된 스케줄을 만들 수 있습니다. 예를 들어, 월요일마다 매주 실행되도록 명령어를 스케줄링할 수 있습니다:

use Illuminate\Support\Facades\Schedule;
 
// 월요일 오후 1시에 일주일에 한 번 실행...
Schedule::call(function () {
    // ...
})->weekly()->mondays()->at('13:00');
 
// 평일 오전 8시부터 오후 5시까지 매시간 실행...
Schedule::command('foo')
          ->weekdays()
          ->hourly()
          ->timezone('America/Chicago')
          ->between('8:00', '17:00');

추가적인 스케줄 제약 조건 목록은 아래에서 찾을 수 있습니다:

요일 제약 조건

days 메소드를 사용하여 작업 실행을 특정 요일로 제한할 수 있습니다. 예를 들어, 일요일과 수요일에 매시간 실행되도록 명령어를 스케줄링할 수 있습니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('emails:send')
                ->hourly()
                ->days([0, 3]);

또는 작업을 실행해야 하는 요일을 정의할 때 Illuminate\Console\Scheduling\Schedule 클래스에서 사용할 수 있는 상수를 사용할 수 있습니다:

use Illuminate\Support\Facades;
use Illuminate\Console\Scheduling\Schedule;
 
Facades\Schedule::command('emails:send')
                ->hourly()
                ->days([Schedule::SUNDAY, Schedule::WEDNESDAY]);

시간 제약 조건 간격

between 메소드를 사용하여 하루 중 시간을 기준으로 작업 실행을 제한할 수 있습니다:

Schedule::command('emails:send')
                    ->hourly()
                    ->between('7:00', '22:00');

마찬가지로 unlessBetween 메소드를 사용하여 특정 시간 동안 작업 실행을 제외할 수 있습니다:

Schedule::command('emails:send')
                    ->hourly()
                    ->unlessBetween('23:00', '4:00');

진실 테스트 제약 조건

when 메소드를 사용하여 지정된 진실 테스트 결과에 따라 작업 실행을 제한할 수 있습니다. 즉, 주어진 클로저가 true를 반환하면 다른 제약 조건이 작업을 실행하지 못하게 하지 않는 한 작업이 실행됩니다:

Schedule::command('emails:send')->daily()->when(function () {
    return true;
});

skip 메소드는 when의 반대로 볼 수 있습니다. skip 메소드가 true를 반환하면 스케줄된 작업이 실행되지 않습니다:

Schedule::command('emails:send')->daily()->skip(function () {
    return true;
});

체인으로 연결된 when 메소드를 사용하는 경우 모든 when 조건이 true를 반환하는 경우에만 스케줄된 명령어가 실행됩니다.

환경 제약 조건

environments 메소드를 사용하여 지정된 환경( APP_ENV 환경 변수에 의해 정의됨)에서만 작업을 실행할 수 있습니다:

Schedule::command('emails:send')
            ->daily()
            ->environments(['staging', 'production']);

시간대

timezone 메소드를 사용하여 스케줄된 작업의 시간을 지정된 시간대 내에서 해석해야 함을 지정할 수 있습니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('report:generate')
         ->timezone('America/New_York')
         ->at('2:00')

모든 스케줄된 작업에 동일한 시간대를 반복적으로 할당하는 경우, 애플리케이션의 app 구성 파일 내에서 schedule_timezone 옵션을 정의하여 모든 스케줄에 할당해야 하는 시간대를 지정할 수 있습니다:

'timezone' => env('APP_TIMEZONE', 'UTC'),
 
'schedule_timezone' => 'America/Chicago',

작업 중복 방지

기본적으로 이전 작업 인스턴스가 여전히 실행 중인 경우에도 스케줄된 작업이 실행됩니다. 이를 방지하려면 withoutOverlapping 메소드를 사용할 수 있습니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('emails:send')->withoutOverlapping();

이 예에서 emails:send Artisan 명령어는 아직 실행 중이 아닌 경우 매분 실행됩니다. withoutOverlapping 메소드는 실행 시간이 크게 다른 작업이 있는 경우에 특히 유용하여 특정 작업에 걸리는 시간을 정확하게 예측할 수 없습니다.

필요한 경우 "중복 없음" 잠금이 만료되기 전에 경과해야 하는 시간(분)을 지정할 수 있습니다. 기본적으로 잠금은 24시간 후에 만료됩니다:

Schedule::command('emails:send')->withoutOverlapping(10);

내부적으로 withoutOverlapping 메소드는 애플리케이션의 캐시를 사용하여 잠금을 얻습니다. 필요한 경우 schedule:clear-cache Artisan 명령어를 사용하여 이러한 캐시 잠금을 지울 수 있습니다. 이는 일반적으로 예기치 않은 서버 문제로 인해 작업이 중단된 경우에만 필요합니다.

하나의 서버에서 작업 실행

애플리케이션의 스케줄러가 여러 서버에서 실행 중인 경우, 스케줄된 작업이 단일 서버에서만 실행되도록 제한할 수 있습니다. 예를 들어 금요일 밤마다 새 보고서를 생성하는 스케줄된 작업이 있다고 가정해 보십시오. 작업 스케줄러가 3개의 작업자 서버에서 실행 중인 경우, 스케줄된 작업은 세 서버 모두에서 실행되고 보고서를 세 번 생성합니다. 좋지 않습니다!

작업이 단일 서버에서만 실행되어야 함을 나타내려면 스케줄된 작업을 정의할 때 onOneServer 메소드를 사용하십시오. 작업을 가져오는 첫 번째 서버는 다른 서버에서 동시에 동일한 작업을 실행하는 것을 방지하기 위해 작업에 대한 원자 잠금을 확보합니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('report:generate')
                ->fridays()
                ->at('17:00')
                ->onOneServer();

단일 서버 작업 이름 지정

때로는 동일한 작업을 서로 다른 매개변수로 디스패치하도록 스케줄링해야 할 수 있지만, 여전히 Laravel에 각 작업 순열을 단일 서버에서 실행하도록 지시해야 할 수 있습니다. 이를 수행하려면 name 메소드를 통해 각 스케줄 정의에 고유한 이름을 할당할 수 있습니다:

Schedule::job(new CheckUptime('https://laravel.com'))
            ->name('check_uptime:laravel.com')
            ->everyFiveMinutes()
            ->onOneServer();
 
Schedule::job(new CheckUptime('https://vapor.laravel.com'))
            ->name('check_uptime:vapor.laravel.com')
            ->everyFiveMinutes()
            ->onOneServer();

마찬가지로, 스케줄된 클로저는 한 서버에서 실행되도록 하려면 반드시 이름을 지정해야 합니다:

Schedule::call(fn () => User::resetApiRequestCount())
    ->name('reset-api-request-count')
    ->daily()
    ->onOneServer();

백그라운드 작업

기본적으로 동시에 예약된 여러 작업은 schedule 메서드에 정의된 순서에 따라 순차적으로 실행됩니다. 시간이 오래 걸리는 작업이 있는 경우, 후속 작업이 예상보다 훨씬 늦게 시작될 수 있습니다. 모든 작업이 동시에 실행될 수 있도록 백그라운드에서 작업을 실행하고 싶다면 runInBackground 메서드를 사용할 수 있습니다.

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('analytics:report')
         ->daily()
         ->runInBackground();

유지보수 모드

서버에서 수행 중인 미완료된 유지보수를 방해하지 않도록 하기 위해, 애플리케이션이 유지보수 모드일 때는 예약된 애플리케이션 작업이 실행되지 않습니다. 그러나 유지보수 모드에서도 강제로 작업을 실행하고 싶다면, 작업을 정의할 때 evenInMaintenanceMode 메서드를 호출할 수 있습니다.

Schedule::command('emails:send')->evenInMaintenanceMode();

스케줄 그룹

유사한 구성으로 여러 예약된 작업을 정의할 때, Laravel의 작업 그룹화 기능을 사용하여 각 작업에 대한 동일한 설정을 반복하지 않을 수 있습니다. 작업 그룹화는 코드를 단순화하고 관련 작업 전반에 걸쳐 일관성을 보장합니다.

예약된 작업 그룹을 생성하려면 원하는 작업 구성 메서드를 호출한 다음 group 메서드를 호출합니다. group 메서드는 지정된 구성을 공유하는 작업을 정의하는 역할을 하는 클로저를 허용합니다.

use Illuminate\Support\Facades\Schedule;
 
Schedule::daily()
    ->onOneServer()
    ->timezone('America/New_York')
    ->group(function () {
        Schedule::command('emails:send --force');
        Schedule::command('emails:prune');
    });

스케줄러 실행하기

이제 예약된 작업을 정의하는 방법을 배웠으니, 실제로 서버에서 작업을 실행하는 방법에 대해 논의해 보겠습니다. schedule:run Artisan 명령어는 예약된 모든 작업을 평가하고 서버의 현재 시간을 기준으로 실행해야 하는지 여부를 결정합니다.

따라서 Laravel 스케줄러를 사용할 때, 우리는 매분마다 schedule:run 명령어를 실행하는 단일 cron 설정 항목을 서버에 추가하기만 하면 됩니다. 서버에 cron 항목을 추가하는 방법을 모르는 경우, cron 항목을 관리해 줄 수 있는 Laravel Forge 와 같은 서비스를 사용하는 것을 고려해 보세요.

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

분 단위 미만 예약된 작업

대부분의 운영 체제에서 cron 작업은 최대 1분에 한 번 실행되도록 제한됩니다. 그러나 Laravel의 스케줄러를 사용하면 1초에 한 번과 같이 더 빈번한 간격으로 작업을 예약할 수 있습니다.

use Illuminate\Support\Facades\Schedule;
 
Schedule::call(function () {
    DB::table('recent_users')->delete();
})->everySecond();

애플리케이션 내에 분 단위 미만 작업이 정의된 경우 schedule:run 명령어는 즉시 종료되지 않고 현재 분의 끝까지 계속 실행됩니다. 이를 통해 명령은 분 단위 동안 필요한 모든 분 단위 미만 작업을 호출할 수 있습니다.

예상보다 오래 걸리는 분 단위 미만 작업은 후속 분 단위 미만 작업의 실행을 지연시킬 수 있으므로 모든 분 단위 미만 작업은 실제 작업 처리를 위해 대기열에 있는 작업 또는 백그라운드 명령을 디스패치하는 것이 좋습니다.

use App\Jobs\DeleteRecentUsers;
 
Schedule::job(new DeleteRecentUsers)->everyTenSeconds();
 
Schedule::command('users:delete')->everyTenSeconds()->runInBackground();

분 단위 미만 작업 중단

분 단위 미만 작업이 정의된 경우 schedule:run 명령이 호출된 전체 분 동안 실행되므로 애플리케이션을 배포할 때 명령을 중단해야 할 수 있습니다. 그렇지 않으면 이미 실행 중인 schedule:run 명령의 인스턴스는 현재 분이 끝날 때까지 애플리케이션의 이전에 배포된 코드를 계속 사용합니다.

진행 중인 schedule:run 호출을 중단하려면 애플리케이션의 배포 스크립트에 schedule:interrupt 명령을 추가하면 됩니다. 이 명령은 애플리케이션 배포가 완료된 후 호출해야 합니다.

php artisan schedule:interrupt

로컬에서 스케줄러 실행하기

일반적으로 로컬 개발 환경에는 스케줄러 cron 항목을 추가하지 않습니다. 대신 schedule:work Artisan 명령어를 사용할 수 있습니다. 이 명령어는 foreground에서 실행되며 명령어를 종료할 때까지 매분마다 스케줄러를 호출합니다. 분 이하의 작업이 정의된 경우, 스케줄러는 해당 작업을 처리하기 위해 매분 내에서 계속 실행됩니다.

php artisan schedule:work

작업 결과

라라벨 스케줄러는 예약된 작업에서 생성된 결과를 다루기 위한 여러 편리한 메서드를 제공합니다. 먼저 sendOutputTo 메서드를 사용하여 나중에 검토할 수 있도록 결과를 파일로 보낼 수 있습니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('emails:send')
         ->daily()
         ->sendOutputTo($filePath);

결과를 지정된 파일에 추가하려면 appendOutputTo 메서드를 사용할 수 있습니다:

Schedule::command('emails:send')
         ->daily()
         ->appendOutputTo($filePath);

emailOutputTo 메서드를 사용하면 선택한 이메일 주소로 결과를 보낼 수 있습니다. 작업 결과를 이메일로 보내기 전에 라라벨의 이메일 서비스를 구성해야 합니다:

Schedule::command('report:generate')
         ->daily()
         ->sendOutputTo($filePath)
         ->emailOutputTo('[email protected]');

예약된 Artisan 또는 시스템 명령이 0이 아닌 종료 코드로 종료되는 경우에만 결과를 이메일로 보내려면 emailOutputOnFailure 메서드를 사용하십시오:

Schedule::command('report:generate')
         ->daily()
         ->emailOutputOnFailure('[email protected]');

작업 후크

before 및 after 메서드를 사용하여 예약된 작업이 실행되기 전과 후에 실행될 코드를 지정할 수 있습니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('emails:send')
         ->daily()
         ->before(function () {
             // 작업이 곧 실행됩니다...
         })
         ->after(function () {
             // 작업이 실행되었습니다...
         });

onSuccess 및 onFailure 메서드를 사용하면 예약된 작업이 성공하거나 실패하는 경우 실행할 코드를 지정할 수 있습니다. 실패는 예약된 Artisan 또는 시스템 명령이 0이 아닌 종료 코드로 종료되었음을 나타냅니다:

Schedule::command('emails:send')
         ->daily()
         ->onSuccess(function () {
             // 작업이 성공했습니다...
         })
         ->onFailure(function () {
             // 작업이 실패했습니다...
         });

명령에서 결과를 사용할 수 있는 경우, 후크의 클로저 정의의 $output 인수로 Illuminate\Support\Stringable 인스턴스를 타입 힌트하여 after, onSuccess 또는 onFailure 후크에서 액세스할 수 있습니다:

use Illuminate\Support\Stringable;
 
Schedule::command('emails:send')
         ->daily()
         ->onSuccess(function (Stringable $output) {
             // 작업이 성공했습니다...
         })
         ->onFailure(function (Stringable $output) {
             // 작업이 실패했습니다...
         });

URL 핑하기

pingBefore 및 thenPing 메서드를 사용하여 스케줄러는 작업이 실행되기 전이나 후에 지정된 URL을 자동으로 핑할 수 있습니다. 이 메서드는 예약된 작업이 시작되거나 실행을 완료했음을 Envoyer와 같은 외부 서비스에 알리는 데 유용합니다:

Schedule::command('emails:send')
         ->daily()
         ->pingBefore($url)
         ->thenPing($url);

pingOnSuccess 및 pingOnFailure 메서드는 작업이 성공하거나 실패한 경우에만 지정된 URL을 핑하는 데 사용할 수 있습니다. 실패는 예약된 Artisan 또는 시스템 명령이 0이 아닌 종료 코드로 종료되었음을 나타냅니다:

Schedule::command('emails:send')
         ->daily()
         ->pingOnSuccess($successUrl)
         ->pingOnFailure($failureUrl);

pingBeforeIf, thenPingIf, pingOnSuccessIf, 및 pingOnFailureIf 메서드는 지정된 조건이 true인 경우에만 지정된 URL을 핑하는 데 사용할 수 있습니다:

Schedule::command('emails:send')
         ->daily()
         ->pingBeforeIf($condition, $url)
         ->thenPingIf($condition, $url);
 
Schedule::command('emails:send')
         ->daily()
         ->pingOnSuccessIf($condition, $successUrl)
         ->pingOnFailureIf($condition, $failureUrl);

이벤트

라라벨은 스케줄링 과정에서 다양한 이벤트를 디스패치합니다. 다음 이벤트에 대한 리스너를 정의할 수 있습니다: