VBA и макросы

Инспекция проекта, планирование и запуск, статус, отмена и откат, доверие к макросам и список одобренных. Термины — в глоссарии.

Операции на этой странице — 12

• cancel_vba_execution
• commit_vba_execution
• get_vba_execution_status
• inspect_vba_project
• list_approved_macros
• list_vba_entrypoints
• macro_trust_lifecycle
• plan_vba_execution
• preview_vba_mutations
• rollback_vba_execution
• run_approved_macro
• start_vba_execution

cancel_vba_execution

Отменяет vba execution.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"cancel_vba_execution"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · cancel_vba_execution

Поле	Тип TypeScript	Обяз.
operation	"cancel_vba_execution"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
outcome	VbaExecutionOutcome	да

Минимальный JSON-шаблон

{
  "operation": "cancel_vba_execution",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

commit_vba_execution

Фиксирует vba execution.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"commit_vba_execution"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · commit_vba_execution

Поле	Тип TypeScript	Обяз.
operation	"commit_vba_execution"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
committed	VbaMutationPreview	да

Минимальный JSON-шаблон

{
  "operation": "commit_vba_execution",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

get_vba_execution_status

Получает vba execution status.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"get_vba_execution_status"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · get_vba_execution_status

Поле	Тип TypeScript	Обяз.
operation	"get_vba_execution_status"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
outcome	VbaExecutionOutcome	да

Минимальный JSON-шаблон

{
  "operation": "get_vba_execution_status",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

inspect_vba_project

Инспектирует vba project.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"inspect_vba_project"	да
subsetId	string	да
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · inspect_vba_project

Поле	Тип TypeScript	Обяз.
operation	"inspect_vba_project"	да
subsetId	string	да
inspection	VbaProjectInspection	да

Минимальный JSON-шаблон

{
  "operation": "inspect_vba_project",
  "subsetId": "<subsetId>",
  "requestedBackend": "native-desktop"
}

list_approved_macros

Возвращает список approved macros.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"list_approved_macros"	да
subsetId	string	да
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · list_approved_macros

Поле	Тип TypeScript	Обяз.	Примечание из контракта
operation	"list_approved_macros"	да
subsetId	string	да
session	ContractSubsetSessionInfo	да
macros	ApprovedMacroDescriptor[]	да
policyNote	string	да	Объясняет, почему список получился именно таким. Пустой список означает одно из двух, и по этому полю их видно: в книге нет читаемого проекта VBA — запускать нечего; либо проект есть, но ни одна его процедура не попала в список разрешённых. Что именно есть в книге, отвечают операции list_vba_entrypoints и plan_vba_execution.

Минимальный JSON-шаблон

{
  "operation": "list_approved_macros",
  "subsetId": "<subsetId>",
  "requestedBackend": "native-desktop"
}

list_vba_entrypoints

Возвращает список vba entrypoints.

Запрос

Поле	Тип TypeScript	Обяз.	Примечание из контракта
operation	"list_vba_entrypoints"	да
subsetId	string	да
userRunnableOnly	boolean	нет	Только те макросы, которые пользователь видит в диалоге «Макросы» Excel.
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · list_vba_entrypoints

Поле	Тип TypeScript	Обяз.	Примечание из контракта
operation	"list_vba_entrypoints"	да
subsetId	string	да
entrypoints	VbaEntrypointDescriptor[]	да	Процедуры, попавшие в ответ: либо все разобранные процедуры проекта, либо — при userRunnableOnly — только видимые в диалоге «Макросы». Длина этого списка зависит от запроса и ничего не говорит о самой книге; для этого есть два поля ниже.
userRunnable	number	да	Сколько макросов пользователь мог бы запустить из диалога «Макросы» и сколько из них выполняются ядром напрямую. Это свойства самой книги: они не пересчитываются из показанного списка, поэтому сужение списка не занижает эти числа. Те же значения возвращает inspect_vba_project.
userRunnableNative	number	да

Минимальный JSON-шаблон

{
  "operation": "list_vba_entrypoints",
  "subsetId": "<subsetId>",
  "requestedBackend": "native-desktop"
}

macro_trust_lifecycle

Запрос

Поле	Тип TypeScript	Обяз.
operation	"macro_trust_lifecycle"	да
subsetId	string	да
intent	ContractMacroTrustIntent	да
readOnly	boolean	нет
protectedView	boolean	нет
trustedLocation	boolean	нет
modifiedAfterSignatureRisk	boolean	нет
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · macro_trust_lifecycle

Поле	Тип TypeScript	Обяз.
operation	"macro_trust_lifecycle"	да
subsetId	string	да
session	ContractSubsetSessionInfo	да
result	ContractMacroTrustResult	да

Минимальный JSON-шаблон

{
  "operation": "macro_trust_lifecycle",
  "subsetId": "<subsetId>",
  "intent": "<ContractMacroTrustIntent>",
  "requestedBackend": "native-desktop"
}

plan_vba_execution

Планирует vba execution.

Запрос

Поле	Тип TypeScript	Обяз.	Примечание из контракта
operation	"plan_vba_execution"	да
subsetId	string	да
entrypoint	string	да	Имя вида Модуль.Процедура — единственный способ адресовать точку входа.
activeSheet	string	да
instructionBudget	number	нет	Предел числа инструкций для одного запуска. Без поля берётся значение по умолчанию для сеанса.
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · plan_vba_execution

Поле	Тип TypeScript	Обяз.
operation	"plan_vba_execution"	да
subsetId	string	да
plan	VbaExecutionPlan	да

Минимальный JSON-шаблон

{
  "operation": "plan_vba_execution",
  "subsetId": "<subsetId>",
  "entrypoint": "<string>",
  "activeSheet": "<string>",
  "requestedBackend": "native-desktop"
}

preview_vba_mutations

Формирует preview для vba mutations.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"preview_vba_mutations"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · preview_vba_mutations

Поле	Тип TypeScript	Обяз.
operation	"preview_vba_mutations"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
preview	VbaMutationPreview	да

Минимальный JSON-шаблон

{
  "operation": "preview_vba_mutations",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

rollback_vba_execution

Откатывает vba execution.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"rollback_vba_execution"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · rollback_vba_execution

Поле	Тип TypeScript	Обяз.	Примечание из контракта
operation	"rollback_vba_execution"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да
restoredCells	number	да	Сколько ячеек вернулось к прежним значениям при откате. Ноль — это полноценный ответ: запуск, не изменивший ни одной ячейки, откатывается так же, как изменивший тысячу.

Минимальный JSON-шаблон

{
  "operation": "rollback_vba_execution",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

run_approved_macro

Запускает approved macro.

Запрос

Поле	Тип TypeScript	Обяз.
operation	"run_approved_macro"	да
subsetId	string	да
macroId	string	да
viewport	ViewportWindow | null	нет
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · run_approved_macro

Поле	Тип TypeScript	Обяз.
operation	"run_approved_macro"	да
subsetId	string	да
session	ContractSubsetSessionInfo	да
macro	ApprovedMacroDescriptor	да
delta	DeltaSummary	да
changedKeys	string[]	да
highlightCellKeys	string[]	да
statusMessage	string	да
activeSheet	ContractActiveSheetMeta	да
geometry	ContractGeometrySubset	да
recalcNeeded	boolean	да
viewport	ViewportWindow	да
previewCells	ContractPreviewCell[]	да

Минимальный JSON-шаблон

{
  "operation": "run_approved_macro",
  "subsetId": "<subsetId>",
  "macroId": "<string>",
  "requestedBackend": "native-desktop"
}

start_vba_execution

Запускает vba execution.

Запрос

Поле	Тип TypeScript	Обяз.	Примечание из контракта
operation	"start_vba_execution"	да
subsetId	string	да
entrypoint	string	да
activeSheet	string	да
instructionBudget	number	нет
shownPlanId	string	нет	Идентификатор плана, который вы показали пользователю перед запуском. Без этого поля запрос планируется и сразу выполняется — как и раньше. С полем добавляется одна проверка: план, описанный запросом, должен совпадать с показанным, иначе приходит отказ automation-plan-stale. Именно это поле придаёт смысл показанному плану: без него можно показать пользователю одни условия запуска, а отправить другие, и контракт этого не заметит.
requestedBackend	ComputeBackendKind | null	нет

Ответ при успехе · start_vba_execution

Поле	Тип TypeScript	Обяз.	Примечание из контракта
operation	"start_vba_execution"	да
subsetId	string	да
sessionId	VbaExecutionSessionId	да	Есть в ответе всегда, даже когда после запуска нечего откатывать. Идентификатор выдаётся до запуска и называет его в любом случае; если откатывать нечего, rollback_vba_execution честно отвечает automation-session-unknown.
outcome	VbaExecutionOutcome	да	Сразу после запуска — running. Дальнейшие запросы состояния возвращают либо ход выполнения, либо итог запуска.

Минимальный JSON-шаблон

{
  "operation": "start_vba_execution",
  "subsetId": "<subsetId>",
  "entrypoint": "<string>",
  "activeSheet": "<string>",
  "requestedBackend": "native-desktop"
}