Настроить преобразование кодом

PUT /api/v1/exports/{export}/transformation

Переключает обычное сопоставление или сохраняет код обработки записей/набора.

Доступ

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

Параметры

Параметры пути: export. Подставьте идентификаторы из ответов своей установки.

Тело запроса (JSON):

{
  "mode": "mapping",
  "source": null,
  "base_version_id": null
}

mode: mapping, records, dataset. base_version_id обязателен, может быть null для первой правки; далее передавайте текущий converter_version_id. Конфликт версии защищает от перезаписи. Режимы.

Язык преобразования

Необязательное поле language: php, javascript, typescript или python. Если поле не передано, сохраняется язык текущей версии преобразования; для нового преобразования используется php. Оно применяется к новому source, а не к языку исходного сценария сбора. При переключении языка передайте новый код на этом языке. Если source не передан или равен null, явная смена языка возвращает 422 с ошибкой поля language; указать тот же язык допустимо, сохранённая версия при этом остаётся прежней.

Для Python используйте def run(ctx):, читайте ctx.params().get('items', []) и возвращайте словари через ctx.emit(). Возврат списка из функции не формирует выгрузку. Режим records сохраняет число и порядок записей, dataset допускает фильтрацию/группировку в пределах лимитов; при обращении к endpoint преобразуется текущая страница. В ответе converter_language указывает язык фактически привязанной версии. base_version_id защищает от конкурентного изменения: используйте текущий converter_version.id, для первого изменения null.

Подробный Python SDK преобразований.

Ответ 200

Сокращённый пример ответа. Дополнительные поля могут присутствовать; числовые идентификаторы условные.

{
  "id": 6,
  "code": "catalog-json",
  "name": "Каталог JSON",
  "format": "json",
  "transformation_mode": "mapping",
  "schema": [
    {
      "source": "sku",
      "target": "id"
    }
  ]
}

Как отправить запрос

В серверном окружении задайте BASE (адрес установки без завершающего слеша) и API_KEY. Секрет не вставляется в исходник. Подготовка клиентов и браузерный JavaScript.

curl

curl --fail-with-body -X PUT "$BASE/api/v1/exports/6/transformation" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "mode": "mapping",
  "source": null,
  "base_version_id": null
}
JSON

Node.js · сервер

// Node.js, сервер. Сохраните как request.mjs.
const response = await fetch(process.env.BASE + "/api/v1/exports/6/transformation", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"mode":"mapping","source":null,"base_version_id":null}),
  signal: AbortSignal.timeout(120000)
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());

Python

import json
import os
import urllib.request
import urllib.error

body = '{"mode":"mapping","source":null,"base_version_id":null}'.encode("utf-8")
request = urllib.request.Request(
    os.environ["BASE"] + "/api/v1/exports/6/transformation",
    method="PUT",
    headers={"Authorization": "Bearer " + os.environ["API_KEY"],
             "Accept": "application/json", "Content-Type": "application/json"},
    data=body,
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        print(json.load(response))
except urllib.error.HTTPError as error:
    print(error.code, error.read().decode("utf-8", errors="replace"))
    raise

PHP · внешний клиент

<?php
$handle = curl_init(getenv("BASE") . "/api/v1/exports/6/transformation");
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("API_KEY"),
        "Accept: application/json",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{"mode":"mapping","source":null,"base_version_id":null}
JSON,
]);
$content = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
if ($content === false) {
    throw new RuntimeException(curl_error($handle));
}
curl_close($handle);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException("HTTP $status: $content");
}
print_r(json_decode($content, true, 512, JSON_THROW_ON_ERROR));

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
    "strings"
)

func main() {
    body := strings.NewReader(`{"mode":"mapping","source":null,"base_version_id":null}`)
    request, err := http.NewRequest("PUT", os.Getenv("BASE") + "/api/v1/exports/6/transformation", body)
    if err != nil { panic(err) }
    request.Header.Set("Authorization", "Bearer " + os.Getenv("API_KEY"))
    request.Header.Set("Accept", "application/json")
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    response, err := client.Do(request)
    if err != nil { panic(err) }
    defer response.Body.Close()
    content, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, content))
    }
    fmt.Println(string(content))
}

Если запрос не выполнен

401: проверьте ключ и срок. 403: права, режим чтения/записи и 2FA. 404: идентификатор и пространство. 422: поля запроса или состояние объекта. 429: подождите Retry-After. Подробно об ошибках и повторах.