# Параметры средства извлечения Контролируйте, как CodeQL CLI система строит базы данных для анализа с помощью опций экстрактора. ## Доступные варианты экстракторов Каждый экстрактор определяет собственный набор конфигурационных опций для создания базы данных с CodeQL запросом из исходного кода. Чтобы узнать, какие опции доступны для конкретного экстрактора, можно выполнить одну из следующих команд: * `codeql resolve languages --format=betterjson` * `codeql resolve extractor --language=LANGUAGE --format=betterjson` Формат `betterjson` выходных данных предоставляет корневые пути средств извлечения и дополнительные сведения. Выходные данные `codeql resolve extractor --language=LANGUAGE --format=betterjson` часто форматируются следующим образом: ```json { "extractor_root" : "/home/user/codeql/java", "extractor_options" : { "option1" : { "title" : "Java extractor option 1", "description" : "An example string option for the Java extractor.", "type" : "string", "pattern" : "[a-z]+" }, "group1" : { "title" : "Java extractor group 1", "description" : "An example option group for the Java extractor.", "type" : "object", "properties" : { "option2" : { "title" : "Java extractor option 2", "description" : "An example array option for the Java extractor", "type" : "array", "pattern" : "[1-9][0-9]*" } } } } } ``` Имена и описания параметров средства извлечения перечислены в разделе `extractor_options`. Каждый параметр может содержать следующие поля: * `title` (обязательно): заголовок параметра * `description` (обязательно): описание параметра * `type` (обязательно): тип параметра, который может быть * `string`: указывает, что параметр может иметь одно строковое значение * `array`: указывает, что параметр может иметь последовательность строковых значений * `object`: указывает, что это не вариант, а группирование, которое может содержать другие параметры и группы параметров. * `pattern` (необязательно): шаблоны регулярных выражений, которые должны соответствовать всем значениям параметра. Обратите внимание, что средство извлечения может наложить дополнительные ограничения на значения параметров, которые не являются или не могут быть выражены в этом шаблоне регулярного выражения. Такие ограничения, если они существуют, будут описаны в поле описания. * `properties` (необязательно): сопоставление имен параметров извлечения в группе параметров с соответствующими описаниями параметра извлечения. Это поле может присутствовать только для групп параметров. Например, параметры `object` типа. В приведенном выше примере средство извлечения объявляет два варианта: * `option1` `string`— это параметр с сопоставлением значений`[a-z]+` * `group1.option2` `array`— это параметр со значениями, соответствующими`[1-9][0-9]\*` ## Команды для настройки опций экстрактора Поддерживается CodeQL CLI настройка опций экстрактора в подкомандах, которые прямо или косвенно вызывают экстракторы. Ниже приведены следующие команды: * `codeql database create` * `codeql database start-tracing` * `codeql database trace-command` * `codeql database index-files` При выполнении этих вложенных команд можно задать параметры средства извлечения с `--extractor-option` помощью параметра CLI. Рассмотрим пример. * `codeql database create --extractor-option java.option1=abc ...` * `codeql database start-tracing --extractor-option java.group1.option2=102 ...` `--extractor-option` требуется ровно один аргумент вида `extractor_option_name=extractor_option_value`: * `extractor_option_name` — имя средства извлечения (в этом примере), `java`за которым следует период, а затем имя параметра средства извлечения (в этом примере `option1` или `group1.option2`). * `extractor_option_value` — значение, назначенное параметру средства извлечения. Значение должно соответствовать шаблону регулярного выражения параметра средства извлечения (если он существует), и он не должен содержать символы новой строки. Использование `--extractor-option` для назначения параметра извлечения, который не существует, является ошибкой. Он CodeQL CLI принимает несколько `--extractor-option` вариантов в одном вызове. Если задать параметр средства извлечения несколько раз, последнее `string` значение параметра перезаписывает все предыдущие. Если задать параметр извлечения массива несколько раз, все значения параметров объединяются в порядке. Кроме того, можно указать имена параметров извлечения без имени средства извлечения. Рассмотрим пример. * `codeql database create --extractor-option option1=abc ...` * `codeql database start-tracing --extractor-option group1.option2=102 ...` Если имя средства извлечения не указано, параметры средства извлечения будут применяться ко всем средствам извлечения, объявляющим параметр с заданным именем. В приведенном выше примере первая команда задала параметр `option1``abc` средства извлечения для `java` средства извлечения и каждого средства извлечения, имеющего параметр `option1`, например `cpp` , средства извлечения, если `option1` параметр средства извлечения существует для этого средства извлечения. ## Формат файла для опций экстрактора Можно также задать параметры средства извлечения с помощью файла. Подкоманды, которые принимают, CodeQL CLI также принимают `--extractor-options-file`, который содержит необходимый аргумент пути к YAML-файлу (с расширением `.yaml` или `.yml`) или JSON-файлу (с расширением `.json`).`--extractor-option` Рассмотрим пример. * `codeql database create --extractor-options-file options.yml ...` * `codeql database start-tracing --extractor-options-file options.json ...` Каждый файл параметра содержит структуру дерева вложенных карт. В корневом каталоге находится ключ карты извлечения, и под ним находятся ключи карты, соответствующие именам средств извлечения. Начиная с третьего уровня, существуют параметры извлечения и группы параметров. В ФОРМАТЕ JSON: ```json { "extractor" : { "java": { "option1" : "abc", "group1" : { "option2" : [ 102 ] } } } } ``` В YAML: ```yaml extractor: java: option1: "abc" group1: option2: [ 102 ] ``` Значение параметра `string` извлечения должно быть строкой или числом (которое будет преобразовано в строку перед дальнейшей обработкой). Значение параметра `array` извлечения должно быть массивом строк или чисел. Значение группы параметров (типа `object`) должно быть картой, которая может содержать вложенные параметры и группы параметров извлечения. Каждое значение параметра извлечения должно соответствовать шаблону регулярного выражения параметра средства извлечения (если оно существует), и он не должен содержать новые символы. Назначение параметра извлечения, который не существует, является ошибкой. Вы можете сделать опции CodeQL CLI игнорирования неизвестного экстрактора, используя специальное `__allow_unknown_properties` булево поле. Например, следующий файл опций просит игнорировать CodeQL CLI все неизвестные опции экстрактора и группы опций в разделе `group1`: ```yaml extractor: java: option1: "abc" group1: __allow_unknown_properties: true option2: [ 102 ] ``` Можно указать `--extractor-options-file` несколько раз. Назначения параметров извлечения обрабатываются в следующем порядке: 1. Все файлы параметров извлечения, указанные в `--extractor-options-file` порядке их отображения в командной строке, затем 1. Все назначения параметров извлечения, указанные в `--extractor-option` порядке их отображения в командной строке Те же правила управляют тем, что происходит, когда один и тот же параметр извлечения устанавливается несколько раз, независимо от того, выполняются ли назначения с помощью, с помощью `--extractor-option``--extractor-options-file`или некоторых сочетаний двух. Если задать параметр средства извлечения несколько раз, последнее `string` значение параметра перезаписывает все предыдущие значения. Если задать `array` параметр средства извлечения несколько раз, все значения параметров объединяются в порядке.