Поделиться через

API выполнения инструкций: запуск SQL в хранилищах

  • Статья

Внимание

Чтобы получить доступ к REST API Databricks, необходимо пройти проверку подлинности.

В этом руководстве показано, как использовать API выполнения инструкций SQL Databricks 2.0 для выполнения инструкций SQL из хранилищ Databricks SQL.

Чтобы просмотреть справочник по API выполнения инструкций SQL Databricks 2.0, см. статью "Выполнение инструкций".

Подготовка к работе

Прежде чем приступить к работе с этим руководством, убедитесь, что у вас есть:

  • Интерфейс командной строки Databricks версии 0.205 или более поздней или curlниже.

    • Интерфейс командной строки Databricks — это средство командной строки для отправки и получения запросов и ответов REST API Databricks. Если вы используете Интерфейс командной строки Databricks версии 0.205 или более поздней, его необходимо настроить для проверки подлинности в рабочей области Azure Databricks. См. статью "Установка или обновление интерфейса командной строки Databricks" и проверки подлинности для интерфейса командной строки Databricks.

      Например, чтобы пройти проверку подлинности с помощью проверки подлинности маркера личного доступа Databricks, выполните действия в Azure Databricks для пользователей рабочей области.

      А затем, чтобы использовать интерфейс командной строки Databricks для создания профиля конфигурации Azure Databricks для личного маркера доступа, сделайте следующее:

      Примечание.

      Следующая процедура использует интерфейс командной строки Databricks для создания профиля конфигурации Azure Databricks с именемDEFAULT. Если у вас уже есть профиль конфигурации, эта процедура перезаписывает существующий DEFAULT DEFAULT профиль конфигурации.

      Чтобы проверить DEFAULT наличие профиля конфигурации и просмотреть параметры этого профиля, если он существует, используйте интерфейс командной строки Databricks для выполнения команды databricks auth env --profile DEFAULT.

      Чтобы создать профиль конфигурации с именем, отличным DEFAULTот имениdatabricks configure, замените DEFAULT часть --profile DEFAULT следующей команды другим именем профиля конфигурации.

      1. Используйте интерфейс командной строки Databricks для создания профиля конфигурации Azure Databricks с именемDEFAULT, использующего проверку подлинности маркера личного доступа Azure Databricks. Для этого выполните следующую команду:

        databricks configure --profile DEFAULT

      2. В поле запроса Databricks Host введите URL-адрес Azure Databricks для каждой рабочей области, напримерhttps://adb-1234567890123456.7.azuredatabricks.net.

      3. В поле запроса персональный маркер доступа введите личный маркер доступа Azure Databricks для рабочей области.

      В примерах интерфейса командной строки Databricks в этом руководстве обратите внимание на следующее:

      • В этом руководстве предполагается, что на локальном компьютере разработки есть переменная DATABRICKS_SQL_WAREHOUSE_ID среды. Эта переменная среды представляет идентификатор хранилища DATAbricks SQL. Этот идентификатор представляет собой строку букв и чисел, приведенных /sql/1.0/warehouses/ в поле пути HTTP для хранилища. Чтобы узнать, как получить значение HTTP-пути к хранилищу, ознакомьтесь с сведениями о подключении для вычислительного ресурса Azure Databricks.
      • Если вы используете командную оболочку Windows вместо командной оболочки для Unix, Linux или macOS, замените \ ее ^и замените ${...} на %...%.
      • Если вы используете командную оболочку Windows вместо командной оболочки для Unix, Linux или macOS, в объявлениях документа JSON замените открытие и закрытие ' и замените внутреннее " \"."

    • curl — это средство командной строки для отправки и получения запросов и ответов REST API. См. также инструкции по установке curl. Или адаптируйте примеры этого руководства curl для использования с аналогичными инструментами, такими как HTTPie.

      В примерах этого руководства curl обратите внимание на следующее:

      • Вместо этого --header "Authorization: Bearer ${DATABRICKS_TOKEN}"можно использовать netrc-файл . Если вы используете .netrc файл, замените --header "Authorization: Bearer ${DATABRICKS_TOKEN}" на --netrc.
      • Если вы используете командную оболочку Windows вместо командной оболочки для Unix, Linux или macOS, замените \ ее ^и замените ${...} на %...%.
      • Если вы используете командную оболочку Windows вместо командной оболочки для Unix, Linux или macOS, в объявлениях документа JSON замените открытие и закрытие ' и замените внутреннее " \"."

      Кроме того, в примерах этого руководства curl предполагается, что на локальном компьютере разработки есть следующие переменные среды:

      • DATABRICKS_HOST, представляющий имя экземпляра рабочей области, например adb-1234567890123456.7.azuredatabricks.netдля рабочей области Azure Databricks.
      • DATABRICKS_TOKEN, представляющий личный маркер доступа Azure Databricks для пользователя рабочей области Azure Databricks.
      • DATABRICKS_SQL_WAREHOUSE_ID, представляющий идентификатор хранилища Databricks SQL. Этот идентификатор представляет собой строку букв и чисел, приведенных /sql/1.0/warehouses/ в поле пути HTTP для хранилища. Чтобы узнать, как получить значение HTTP-пути к хранилищу, ознакомьтесь с сведениями о подключении для вычислительного ресурса Azure Databricks.

      Примечание.

      В качестве рекомендации по обеспечению безопасности при проверке подлинности с помощью автоматизированных средств, систем, сценариев и приложений Databricks рекомендуется использовать личные маркеры доступа, принадлежащие субъектам-службам, а не пользователям рабочей области. Сведения о создании маркеров для субъектов-служб см. в разделе "Управление маркерами" для субъекта-службы.

      Чтобы создать личный маркер доступа Azure Databricks, следуйте инструкциям в маркерах личного доступа Azure Databricks для пользователей рабочей области.

      Предупреждение

      Databricks настоятельно не рекомендует жестко кодировать информацию в скриптах, так как эта конфиденциальная информация может быть предоставлена в виде обычного текста с помощью систем управления версиями. Databricks рекомендует использовать такие подходы, как переменные среды, заданные на компьютере разработки. Удаление таких жестко закодированных сведений из скриптов помогает сделать эти скрипты более переносимыми.

  • В этом руководстве предполагается, что у вас также есть jq, обработчик командной строки для запроса полезных данных ответа JSON, которые API выполнения инструкций Databricks SQL возвращается вам после каждого вызова, который вы выполняете в API выполнения инструкции Databricks SQL. См. раздел "Скачать jq".

  • Необходимо иметь по крайней мере одну таблицу, в которую можно выполнять инструкции SQL. Это руководство основано на lineitem таблице в tpch схеме (также известной как база данных) в каталоге samples . Если у вас нет доступа к этому каталогу, схеме или таблице из рабочей области, замените их в этом руководстве собственным.

Шаг 1. Выполнение инструкции SQL и сохранение результата данных в формате JSON

Выполните следующую команду:

  1. Использует указанное хранилище SQL, а также указанный маркер при использовании curl, чтобы запросить три столбца из первых lineitem двух строк таблицы в схеме в tcph каталоге samples .
  2. Сохраняет полезные данные ответа в формате JSON в файле с именем sql-execution-response.json в текущем рабочем каталоге.
  3. Выводит содержимое sql-execution-response.json файла.
  4. Задает переменную локальной среды с именем SQL_STATEMENT_ID. Эта переменная содержит идентификатор соответствующей инструкции SQL. Этот идентификатор инструкции SQL можно использовать для получения сведений об этой инструкции позже по мере необходимости, которая показана на шаге 2. Вы также можете просмотреть эту инструкцию SQL и получить его идентификатор из раздела журнала запросов консоли SQL Databricks или вызвав API журнала запросов.
  5. Задает дополнительную локальную переменную среды с именем NEXT_CHUNK_EXTERNAL_LINK , содержащую фрагмент URL-адреса API для получения следующего фрагмента данных JSON. Если данные ответа слишком большие, API выполнения инструкции Databricks SQL предоставляет ответ в блоках. Этот фрагмент URL-адреса API можно использовать для получения следующего фрагмента данных, который показан на шаге 2. Если следующий блок отсутствует, то для этой переменной среды задано значение null.
  6. Выводит значения SQL_STATEMENT_ID переменных среды и NEXT_CHUNK_INTERNAL_LINK переменных среды.

Интерфейс командной строки Databricks

databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Замените <profile-name> именем профиля конфигурации Azure Databricks для проверки подлинности.

curl

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

В предыдущем запросе:

  • Параметризованные запросы состоят из имени каждого параметра запроса, предшествующего двоеточию (например, :extended_price) с соответствующим name и value объектом в массиве parameters . Кроме того, можно указать необязательное type значение STRING по умолчанию, если оно не указано.

    Предупреждение

    Databricks настоятельно рекомендует использовать параметры в качестве рекомендации для инструкций SQL.

    Если вы используете API выполнения инструкций Databricks с приложением, которое создает SQL динамически, это может привести к атакам внедрения SQL. Например, если вы создаете код SQL на основе выбора пользователя в пользовательском интерфейсе и не принимает соответствующие меры, злоумышленник может внедрить вредоносный код SQL для изменения логики первоначального запроса, тем самым считывая, изменяя или удаляя конфиденциальные данные.

    Параметризованные запросы помогают защитить от атак на внедрение SQL, обрабатывая входные аргументы отдельно от остальной части кода SQL и интерпретируя эти аргументы в виде литеральных значений. Параметры также помогают повторно использовать код.

  • По умолчанию все возвращаемые данные отображаются в формате массива JSON, а расположение по умолчанию для любого из результатов данных инструкции SQL находится в полезных данных ответа. Чтобы сделать это поведение явным, добавьте "format":"JSON_ARRAY","disposition":"INLINE" полезные данные запроса. Если вы пытаетесь вернуть результаты данных размером более 25 МиБ в полезных данных ответа, возвращается состояние сбоя, а инструкция SQL отменяется. Для результатов данных размером более 25 МиБ можно использовать внешние ссылки, а не пытаться вернуть их в полезные данные ответа, которое показано на шаге 3.

  • Команда сохраняет содержимое полезных данных ответа в локальный файл. Локальное хранилище данных не поддерживается API выполнения инструкций Databricks SQL напрямую.

  • По умолчанию через 10 секунд, если инструкция SQL еще не завершена выполнение через хранилище, API выполнения инструкции Databricks SQL возвращает только идентификатор инструкции SQL и его текущее состояние, а не результат инструкции. Чтобы изменить это поведение, добавьте "wait_timeout" в запрос и задайте для него значение "<x>s", где <x> может находиться в диапазоне от 5 секунд до 50 секунд включительно, например "50s". Чтобы вернуть идентификатор инструкции SQL и его текущее состояние немедленно, задайте значение wait_timeout 0s.

  • По умолчанию инструкция SQL продолжает выполняться, если достигается период времени ожидания. Чтобы отменить инструкцию SQL, если достигнут период времени ожидания, добавьте "on_wait_timeout":"CANCEL" в полезные данные запроса.

  • Чтобы ограничить возвращенное число байтов, добавьте "byte_limit" в запрос и задайте для него число байтов, например 1000.

  • Чтобы ограничить количество возвращаемых строк, вместо добавления LIMIT предложения statementв запрос можно добавить "row_limit" в запрос и задать для него число строк, например "statement":"SELECT * FROM lineitem","row_limit":2.

  • Если результат больше указанного byte_limit или row_limittruncated , поле задается true в полезных данных ответа.

Если результат инструкции доступен до окончания времени ожидания, ответ выглядит следующим образом:

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 2,
        "row_offset": 0
      }
    ],
    "format": "JSON_ARRAY",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_chunk_count": 1,
    "total_row_count": 2,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [
      [
        "2",
        "71433.16",
        "1997-01-28"
      ],
      [
        "7",
        "86152.02",
        "1996-01-15"
      ]
    ],
    "row_count": 2,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Если время ожидания заканчивается до того, как будет доступен результат инструкции, ответ выглядит следующим образом:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Если данные результатов инструкции слишком большие (например, при выполнении SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), то результирующий результат будет фрагментирован и выглядит следующим образом. Обратите внимание, что "...": "..." результаты опущены здесь для краткости:

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 188416,
        "row_offset": 0
      },
      {
        "chunk_index": 1,
        "row_count": 111584,
        "row_offset": 188416
      }
    ],
    "format":"JSON_ARRAY",
    "schema": {
      "column_count":3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_chunk_count": 2,
    "total_row_count": 300000,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [
      [
        "2",
        "71433.16",
        "1997-01-28"
      ],
      [
        "..."
      ]
    ],
    "next_chunk_index": 1,
    "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=188416",
    "row_count": 188416,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Шаг 2. Получение текущего состояния выполнения инструкции и результата данных в формате JSON

Идентификатор инструкции SQL можно использовать для получения текущего состояния выполнения инструкции и, если выполнение выполнено успешно, результат этого оператора. Если вы забыли идентификатор инструкции, его можно получить из раздела журнала запросов консоли SQL Databricks или путем вызова API журнала запросов. Например, вы можете провести опрос этой команды, проверяя каждый раз, чтобы узнать, успешно ли выполнено выполнение.

Чтобы получить текущее состояние выполнения инструкции SQL и, если выполнение выполнено успешно, результат инструкции и фрагмент URL-адреса API для получения любого следующего фрагмента данных JSON выполните следующую команду. Эта команда предполагает, что на локальном компьютере SQL_STATEMENT_IDразработки есть переменная среды, которая имеет значение идентификатора инструкции SQL на предыдущем шаге. Конечно, можно заменить ${SQL_STATEMENT_ID} в следующей команде жестко закодированный идентификатор инструкции SQL.

Интерфейс командной строки Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Замените <profile-name> именем профиля конфигурации Azure Databricks для проверки подлинности.

curl

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

NEXT_CHUNK_INTERNAL_LINK Если заданоnull значение, отличное от значения, его можно использовать для получения следующего блока данных и т. д., например с помощью следующей команды:

Интерфейс командной строки Databricks

databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Замените <profile-name> именем профиля конфигурации Azure Databricks для проверки подлинности.

curl

curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Чтобы получить следующий блок и т. д., можно продолжать выполнять предыдущую команду, снова и снова. Обратите внимание, что после получения последней блоки инструкция SQL закрывается. После этого закрытия идентификатор инструкции нельзя использовать для получения текущего состояния или получения дополнительных фрагментов.

В этом разделе демонстрируется необязательная конфигурация, которая использует EXTERNAL_LINKS ликвидацию для получения больших наборов данных. Расположение по умолчанию (ликвидация) для данных результатов инструкции SQL находится в полезных данных ответа, но эти результаты ограничены 25 МиБ. Задав disposition значение EXTERNAL_LINKS, ответ содержит URL-адреса, которые можно использовать для получения фрагментов данных результатов с помощью стандартного ПРОТОКОЛА HTTP. URL-адреса указывают на внутреннюю базу данных рабочей области, где результаты блоки временно хранятся.

Предупреждение

Databricks настоятельно рекомендует защитить URL-адреса и маркеры, возвращаемые ликвидацией EXTERNAL_LINKS .

При использовании EXTERNAL_LINKS ликвидации создается URL-адрес сигнатуры общего доступа (SAS), который можно использовать для скачивания результатов непосредственно из хранилища Azure. Так как кратковременный маркер SAS внедрен в этот URL-адрес SAS, необходимо защитить URL-адрес SAS и маркер SAS.

Так как URL-адреса SAS уже создаются с внедренными временными маркерами SAS, не следует задавать Authorization заголовок в запросах загрузки.

Ликвидация EXTERNAL_LINKS может быть отключена по запросу, создав вариант поддержки.

См. также рекомендации по обеспечению безопасности.

Примечание.

Выходной формат и поведение выходных данных отклика, если они заданы для определенного идентификатора инструкции SQL, нельзя изменить.

В этом режиме API позволяет хранить данные результатов в формате JSON (), формате CSV (JSONCSV) или формате Apache Arrow (ARROW_STREAM), которые должны запрашиваться отдельно с помощью HTTP. Кроме того, при использовании этого режима невозможно встраивать данные результатов в полезные данные ответа.

Следующая команда демонстрирует использование EXTERNAL_LINKS и формат Apache Arrow. Используйте этот шаблон вместо аналогичного запроса, показанного на шаге 1.

Интерфейс командной строки Databricks

databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

Замените <profile-name> именем профиля конфигурации Azure Databricks для проверки подлинности.

curl

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

Ответ выглядит следующим образом:

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "row_count": 100000,
        "row_offset": 0
      }
    ],
    "format": "ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_byte_count": 2843848,
    "total_chunk_count": 1,
    "total_row_count": 100000,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "row_count": 100000,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Если запрос истекает, ответ выглядит следующим образом:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Чтобы получить текущее состояние выполнения инструкции и, если выполнение выполнено успешно, выполните следующую команду:

Интерфейс командной строки Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Замените <profile-name> именем профиля конфигурации Azure Databricks для проверки подлинности.

curl

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Если ответ достаточно велик (например, при выполнении SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem без ограничения строки), ответ будет иметь несколько блоков, как показано в следующем примере ниже. Обратите внимание, что "...": "..." результаты опущены здесь для краткости:

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "row_count": 403354,
        "row_offset": 0
      },
      {
        "byte_count": 6282464,
        "chunk_index": 1,
        "row_count": 220939,
        "row_offset": 403354
      },
      {
        "...": "..."
      },
      {
        "byte_count": 6322880,
        "chunk_index": 10,
        "row_count": 222355,
        "row_offset": 3113156
      }
    ],
    "format":"ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_byte_count": 94845304,
    "total_chunk_count": 11,
    "total_row_count": 3335511,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "next_chunk_index": 1,
        "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=403354",
        "row_count": 403354,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Чтобы скачать результаты сохраненного содержимого, можно выполнить следующую curl команду, используя URL-адрес объекта external_link и указав место загрузки файла. Не включайте маркер Azure Databricks в следующую команду:

curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"

Чтобы скачать определенный фрагмент результатов потокового содержимого, можно использовать одно из следующих элементов:

  • next_chunk_index Значение из полезных данных ответа для следующего блока (если есть следующий блок).
  • Один из индексов блока из манифеста полезных данных ответа для любого доступного блока, если существует несколько блоков.

Например, чтобы получить блок с предыдущим ответом chunk_index 10 , выполните следующую команду:

Интерфейс командной строки Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Замените <profile-name> именем профиля конфигурации Azure Databricks для проверки подлинности.

curl

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Примечание.

При выполнении предыдущей команды возвращается новый URL-адрес SAS.

Чтобы скачать сохраненный блок, используйте URL-адрес в объекте external_link .

Дополнительные сведения о формате Apache Arrow см. в следующих статье:

Шаг 4. Отмена выполнения инструкции SQL

Если необходимо отменить инструкцию SQL, которая еще не выполнена, выполните следующую команду:

Интерфейс командной строки Databricks

databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'

Замените <profile-name> именем профиля конфигурации Azure Databricks для проверки подлинности.

curl

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

Рекомендации по обеспечению безопасности

API выполнения инструкций Databricks SQL повышает безопасность передачи данных с помощью сквозного шифрования протокола TLS и коротких учетных данных, таких как маркеры SAS.

В этой модели безопасности существует несколько уровней. На транспортном уровне можно вызывать API выполнения инструкций Databricks SQL только с помощью TLS 1.2 или более поздней версии. Кроме того, вызывающие API выполнения инструкций Databricks SQL должны пройти проверку подлинности с помощью допустимого маркера личного доступа Azure Databricks, маркера доступа OAuth или идентификатора Microsoft Entra (ранее Azure Active Directory), который сопоставляется с пользователем, у которого есть право использовать Databricks SQL. Этот пользователь должен иметь доступ CAN USE для конкретного используемого хранилища SQL, и доступ может быть ограничен списками IP-доступа. Это относится ко всем запросам к API выполнения инструкций Databricks SQL. Кроме того, для выполнения инструкций пользователь, прошедший проверку подлинности, должен иметь разрешение на объекты данных (например, таблицы, представления и функции), которые используются в каждой инструкции. Это применяется существующими механизмами управления доступом в каталоге Unity или с помощью списков управления доступом таблицы. (См. раздел Для получения дополнительных сведений об управлении данными с помощью каталога Unity.) Это также означает, что только пользователь, выполняющий инструкцию, может выполнять запросы на получение результатов инструкции.

Databricks рекомендует следующие рекомендации по обеспечению безопасности при использовании API выполнения инструкций Databricks SQL вместе с EXTERNAL_LINKS ликвидацией для получения больших наборов данных:

  • Удаление заголовка авторизации Databricks для запросов службы хранилища Azure
  • Защита URL-адресов и маркеров SAS

Ликвидация EXTERNAL_LINKS может быть отключена по запросу, создав вариант поддержки. Чтобы сделать этот запрос, обратитесь к группе учетной записи Azure Databricks.

Удаление заголовка авторизации Databricks для запросов службы хранилища Azure

Все вызовы API выполнения инструкций Databricks SQL, которые используются curl , должны содержать Authorization заголовок, содержащий учетные данные доступа к Azure Databricks. Не включать этот Authorization заголовок всякий раз при скачивании данных из хранилища Azure. Этот заголовок не требуется и может непреднамеренно предоставлять учетные данные доступа к Azure Databricks.

Защита URL-адресов и маркеров SAS

При использовании EXTERNAL_LINKS ликвидации создается короткий URL-адрес SAS, который вызывающий объект может использовать для скачивания результатов непосредственно из хранилища Azure с помощью TLS. Так как кратковременный маркер SAS внедрен в этот URL-адрес SAS, необходимо защитить URL-адрес SAS и маркер SAS.