Criar um agendamento - : Central de Documentação do Alibaba Cloud

Crie uma configuração de execução para acionar um Template conforme um cronograma ou sob demanda.

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <PAT>`
`Content-Type`	Sim	`application/json`
`Idempotency-Key`	Não	Chave de idempotência opcional para requisições não seguras.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`identity_id`	string	Sim	ID da Identity proprietária do Schedule.
`template_id`	string	Sim	ID do Template a executar.
`name`	string	Sim	Nome do agendamento.
`description`	string	Não	Descrição do agendamento.
`initial_events`	array	Sim	Eventos injetados em cada execução. Atualmente, há suporte apenas para `user.message`.
`execution`	object	Não	Política de execução. O sistema aplica os valores padrão se este campo for omitido.
`trigger_policy`	object	null	Não	Política de acionamento. Se omitido ou definido como `null`, assume o valor `{"type":"manual"}`.
`environment_id`	string	Sim	Ambiente de execução.
`metadata`	object	Não	Metadados personalizados exclusivos para rótulos ou dados de passagem.

Política de acionamento

`type`	Entrada obrigatória	Descrição
`cron`	`type`, `expression`, `timezone`	Aciona com base em uma expressão cron de 5 campos no fuso horário IANA especificado.
`once`	`type`, `expression`, `timezone` opcional	Executa uma única vez em um horário ISO 8601. O campo `timezone` é obrigatório quando a expressão não possui offset.
`interval`	`type`, `expression`	Repete em um intervalo de duração fixa ISO 8601, como `PT15M`.
`manual`	`type`	Nunca executa automaticamente. Use o endpoint Execute Schedule para acionar.

Política de execução

Campo	Tipo	Padrão	Descrição
`session_mode`	string	`new_session`	`new_session` ou `reuse_session`.
`max_concurrent_runs`	integer	1	Número máximo de execuções simultâneas para este Schedule.
`max_attempts`	integer	1	Reservado. O sistema registra e valida o valor, mas executa apenas uma tentativa.
`timeout_ms`	integer	300000	Tempo limite por tentativa.

Exemplo de requisição

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/schedules' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "idn_019eabc123",
    "template_id": "tmpl_support",
    "name": "Daily tech brief",
    "description": "Generate a daily technology news summary",
    "initial_events": [
      {
        "type": "user.message",
        "content": "Summarize current technology news in five bullet points."
      }
    ],
    "trigger_policy": {
      "type": "cron",
      "expression": "0 9 * * *",
      "timezone": "Asia/Shanghai"
    },
    "execution": {
      "session_mode": "new_session",
      "max_concurrent_runs": 1,
      "max_attempts": 1,
      "timeout_ms": 300000
    },
    "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c"
  }'

Exemplo de resposta

HTTP 200 OK

{
  "id": "sched_019f00112233445566778899aabbccdd",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "Daily tech brief",
  "description": "Generate a daily technology news summary",
  "status": "active",
  "paused_reason": null,
  "initial_events": [
    {
      "type": "user.message",
      "content": "Summarize current technology news in five bullet points."
    }
  ],
  "execution": {
    "session_mode": "new_session",
    "max_concurrent_runs": 1,
    "max_attempts": 1,
    "timeout_ms": 300000
  },
  "trigger_policy": {
    "type": "cron",
    "expression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "upcoming_runs_at": ["2026-06-23T01:00:00Z"]
  },
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "sinks": [],
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:00:00Z"
}

Erros

HTTP	Tipo	Código	Gatilho
400	`invalid_request_error`	`invalid_trigger_policy`	Tipo ou expressão da política de acionamento inválido.
400	`invalid_request_error`	`trigger_policy_too_frequent`	Intervalo de acionamento inferior a um minuto.
400	`invalid_request_error`	`trigger_policy_time_too_soon`	Horário alvo do tipo `once` muito próximo.
400	`invalid_request_error`	`unsupported_sinks_input`	Corpo da requisição contém `sinks`.
404	`not_found_error`	`identity_not_found`	Identity não existe.
404	`not_found_error`	`template_not_found`	Template não existe.
401	`authentication_error`	`authentication_required`	PAT inválido ou expirado.

Observações

O endpoint de criação não aceita sinks. Agendamentos criados via API retornam sinks: [].
Agendamentos do tipo manual só podem ser acionados com POST /api/v1/forward/schedules/{schedule_id}/run.
Agendamentos do tipo once são arquivados automaticamente após a primeira execução atingir um estado terminal.

Cabeçalhos da requisição

Corpo da requisição

Política de acionamento

Política de execução

Exemplo de requisição

Exemplo de resposta

Erros

Observações

APIs relacionadas