Связаться с намиПодключиться

Метод TransactWriteItems

Статья создана
Обновлена 12 июля 2022 г.

Синхронная операция записи, которая группирует до 25 действий. Можно работать с элементами из разных таблиц, но с одним элементом за один запрос можно выполнять только одно действие.

Суммарный объем всех элементов не может превышать 4 Мб.

Метод атомарен, так что либо выполнятся все действия, либо ни одного. Причины отклонения описаны в ошибке TransactionCanceledException.

Действия, которые можно выполнить:

  • Put — запись нового элемента.
  • Update — обновление существующего элемента.
  • Delete — удаление существующего элемента.
  • ConditionCheck — условие для проверки существования элемента или состояния его атрибутов.

Запрос

Запрос содержит данные в формате JSON.

{
   "ReturnConsumedCapacity": "string",
   "TransactItems": [ 
      { 
         "ConditionCheck": { 
            "ConditionExpression": "string",
            "ExpressionAttributeNames": { 
               "string" : "string" 
            },
            "ExpressionAttributeValues": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "Key": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string"
         },
         "Delete": { 
            "ConditionExpression": "string",
            "ExpressionAttributeNames": { 
               "string" : "string" 
            },
            "ExpressionAttributeValues": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "Key": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string"
         },
         "Put": { 
            "ConditionExpression": "string",
            "ExpressionAttributeNames": { 
               "string" : "string" 
            },
            "ExpressionAttributeValues": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "Item": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string"
         },
         "Update": { 
            "ConditionExpression": "string",
            "ExpressionAttributeNames": { 
               "string" : "string" 
            },
            "ExpressionAttributeValues": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "Key": { 
               "string" : { 
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [ 
                     "AttributeValue"
                  ],
                  "M": { 
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            },
            "ReturnValuesOnConditionCheckFailure": "string",
            "TableName": "string",
            "UpdateExpression": "string"
         }
      }
   ]
}

Параметры

Параметр Описание
TransactItems Упорядоченный массив из объектов типа TransactWriteItem, каждый из которых содержит операцию Put, Update, Delete или ConditionCheck. Можно работать с элементами из разных таблиц, но каждый элемент в одном запросе можно использовать только один раз..

Тип: массив объектов TransactWriteItem
Элементы массива: 1-25 элементов.
Обязательно: Да
ClientRequestToken Не поддерживается. Не зависимо от значений ттокена все вызовы метода будут идемпотентным. Это означает, что повторные вызовы метода будут иметь тот же эффект, то и единичный вызов.
Хотя состояние сервера не изменится, но ответы могут быть разными. Если установлен параметр ReturnConsumedCapacity, то при первом запросе вернется количество единиц емкости записи. Последующие запросы с тем же токеном будут возвращать количество единиц емкости чтения.
Токен действителен в течение 10 минут после выполнения первого запроса. После этого любой запрос с тем же токеном считается как новый запрос.
Если в течение 10 минут отправить такой же токен, но с другими параметрами, то метод вернет исключение IdempotentParameterMismatch.

Тип: Строка
Длина: 1 - 36 символов.
Обязательно: Нет
ReturnConsumedCapacity Нужно ли возвращать информацию о потребляемой мощности.
  • TOTAL - Вернуть информацию.
  • NONE - Не возвращать информацию.

Тип: Строка
Возможные значения: TOTAL | NONE
Обязательно: Нет

Ответ

В случае успеха вернется HTTP с кодом 200.
Запрос возвращает данные в формате JSON.

{
   "ConsumedCapacity": [ 
      { 
         "CapacityUnits": number,
         "GlobalSecondaryIndexes": { 
            "string" : { 
               "CapacityUnits": number,
               "ReadCapacityUnits": number,
               "WriteCapacityUnits": number
            }
         },
         "LocalSecondaryIndexes": { 
            "string" : { 
               "CapacityUnits": number,
               "ReadCapacityUnits": number,
               "WriteCapacityUnits": number
            }
         },
         "ReadCapacityUnits": number,
         "Table": { 
            "CapacityUnits": number,
            "ReadCapacityUnits": number,
            "WriteCapacityUnits": number
         },
         "TableName": "string",
         "WriteCapacityUnits": number
      }
   ]
}

Параметры

Параметр Описание
ConsumedCapacity Единицы мощности, потребленные операцией удаления.
Возвращается только в том случае, если в запросе был указан параметр ReturnConsumedCapacity со значением TOTAL.

Тип: объект типа ConsumedCapacity

Ошибки

Параметр Описание
IdempotentParameterMismatchException Запрос отклонен, т.к. он содержит идемпотентный токен с другими параметрами.

Код состояния HTTP: 400
InternalServerError Произошла внутренняя ошибка на стороне сервера.

Код состояния HTTP: 500
ProvisionedThroughputExceededException Вы слишком часто отправляете запросы. Попробуйте увеличить интервалы между запросами.
Если таких запросов будет не слишком много, Managed Service for YDB постарается обработать их все.

Код состояния HTTP: 400
RequestLimitExceeded Пропускная способность превышает квоту.

Код состояния HTTP: 400
ResourceNotFoundException Указанная таблица не существует.

Код состояния HTTP: 400
TransactionCanceledException Весь запрос целиком был отменен.
Это может произойти в следующих случаях:
  • Условие в одном из выражений не выполняется.
  • Попытка выполнить несколько действий над одним элементом в одном запросе.
  • Для завершения транзакции недостаточно выделенной емкости.
  • Размер отдельного элемента слишком большой (более 400 Кб). Или возникает аналогичная ошибка из-за изменений, внесенных транзакцией.
  • Общий размер всех элементов превышает 4 Мб.
  • Ошибка пользователя, например неверный формат данных.

Код состояния HTTP: 400
TransactionInProgressException Транзакция с указанным токеном запроса уже выполняется.

Код состояния HTTP: 400

Также могут возникать Общие ошибки, одинаковые для всех методов.

Предыдущая
TransactGetItems
Следующая
UpdateItem