Руководство пользователя для разработчиков

Руководство пользователя для разработчиков

Вызовы к SQL API

Epsilon Metrics основан на надежной базе данных PostgreSQL. Все ваши таблицы находятся в одной базе данных, что позволяет выполнять сложные запросы с объединением таблиц или проводить геопространственные операции. Лучшее место для изучения языка SQL PostgreSQL - официальная документация.

Epsilon Metrics также основан на PostGIS, поэтому вы можете просмотреть официальный справочник PostGIS чтобы узнать, какие функции мы поддерживаем в отношении геопространственных операций. Все наши таблицы содержат столбец под названием the_geom, который является геометрическим полем, индексирующим геометрию в системе координат EPSG:4326 (WGS 1984). Все таблицы также имеют автоматически генерируемый и обновляемый столбец под названием the_geom_webmercator. Мы используем этот столбец внутренне для быстрого создания тайлов для карт.

URL-конечные точки

Все запросы к SQL API вашего аккаунта Epsilon Metrics должны следовать этому общему шаблону:

Пример SQL-запроса

https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?q={SQL statement}

Если возникают ошибки, удвойте проверку правильности имени учетной записи и корректности вашего SQL-запроса. Простой пример этого шаблона - подсчет всех записей в вашей таблице:

Пример подсчета

https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?q=SELECT count(*) FROM {table_name}

Результат

{
  time: 0.007,
  total_rows: 1,
  rows: [
    {
      count: 4994
    }
  ]
}

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

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

https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?api_key={your_api_key}&q=SELECT count(*) FROM {table_name}

POST и GET

Epsilon Metrics SQL API настроен на обработку запросов GET и POST. Вы можете протестировать метод GET прямо в вашем браузере. Ниже приведен пример запроса jQuery SQL API в Epsilon Metrics:

jQuery

Вызов

$.getJSON('https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/?q='+sql_statement, function(data) {
  $.each(data.rows, function(key, val) {
    // делайте что-нибудь!
  });
});

По умолчанию, запросы GET работают откуда угодно. В Epsilon Metrics запросы POST также работают с любого сайта. Мы достигаем этого, размещая файл политики кросс-домена на корневом уровне всех наших серверов. Это позволяет вам обеспечить наивысшую гибкость при разработке вашего приложения.

Форматы ответа

SQL API поддерживает множество форматов вывода, которые могут быть полезны для экспорта данных, таких как:

  • GPKG
  • CSV
  • SHP
  • SVG
  • KML
  • SpatiaLite
  • GeoJSON

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

JSON
Вызов
https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1
Результат
{
  time: 0.006,
  total_rows: 1,
  rows: [
    {
      year: "  2011",
      month: 10,
      day: "11",
      the_geom: "0101000020E610...",
      cartodb_id: 1,
      the_geom_webmercator: "0101000020110F000..."
    }
  ]
}

В качестве альтернативы, вы можете использовать спецификацию GeoJSON для возврата данных из API. Чтобы сделать это, просто предоставьте параметр format как GeoJSON:

GeoJSON
Вызов
https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?format=GeoJSON&q=SELECT * FROM {table_name} LIMIT 1
Результат
{
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      properties: {
        year: "  2011",
        month: 10,
        day: "11",
        cartodb_id: 1
      },
      geometry: {
        type: "Point",
        coordinates: [
          -97.335,
          35.498
        ]
      }
    }
  ]
}

Имя файла вывода

Чтобы настроить имя выходного файла, добавьте параметр filename в ваш URL:

Вызов
https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?filename={custom_filename}&q=SELECT * FROM {table_name} LIMIT 1

Получение информации о таблице

В настоящее время нет общедоступного метода для доступа к схемам вашей таблицы. Простейший способ получить структуру таблицы - получить доступ к первой строке данных:

Вызов
https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?q=SELECT * FROM {table_name} LIMIT 1

Ошибки ответа

Чтобы помочь вам отладить ваши SQL-запросы, SQL API Epsilon Metrics возвращает полную ошибку, предоставленную PostgreSQL, как часть ответа в формате JSON. Ошибки ответа выглядят следующим образом:

Результат
{
  error: [
    "syntax error at or near \"LIMIT\""
  ]
}

ПРЕДУПРЕЖДЕНИЕ: Если база данных обнаруживает ошибку после начала передачи ответа, заголовок ошибки все равно будет установлен, но код состояния HTTP будет 200.

Вы можете использовать эти ошибки для лучшего понимания вашего SQL. Если вы столкнетесь с ошибками выполнения SQL, либо через конструктор Epsilon Metrics, либо через SQL API, рекомендуется выполнить поиск ошибки в Google для самостоятельного устранения неполадок.

Запись данных в ваш аккаунт Epsilon Metrics

При записи данных в ваш аккаунт Epsilon Metrics вы выполняете SQL-запросы для управления данными в таблице. Выполнение вставок или обновлений данных достигается с использованием вашего API ключа. Просто предоставьте правильно отформатированный SQL-запрос INSERT или UPDATE для вашей таблицы, а также параметр api_key для вашего аккаунта.

Важно: Все запросы должны быть приватными, так как любой, у кого есть ваш API ключ, сможет изменять ваши таблицы.

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

Вставка
Вызов
https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?q=INSERT INTO test_table (column_name, column_name_2, the_geom) VALUES ('this is a string', 11, ST_SetSRID(ST_Point(-110, 43),4326))&api_key=api_key

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

Обновление
Вызов
https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql?q=UPDATE test_table SET column_name = 'my new string value' WHERE cartodb_id = 1 &api_key=api_key