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

Метод PutItem

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

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

Можно задать условие. Тогда метод отработает только в том случае, если условие выполнится.

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

Запрос

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

{
   "ConditionalOperator": "string",
   "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" ]
      }
   },
   "ReturnConsumedCapacity": "string",
   "ReturnValues": "string",
   "TableName": "string"
}

Параметры

Параметр Описание
Item Ассоциативный массив атрибутов вида ключ/значение.
Обязательны только атрибуты первичного ключа, но можно указать и другие атрибуты.
Для первичного ключа необходимо указать все его ключевые атрибуты. Для простого ключа нужно указать только его значение. Для составного первичного ключа нужно указать значение ключа раздела и ключа сортировки.
Значения строковых и двоичных атрибутов могут быть пустыми.

Тип: объект типа AttributeValue
Длина: 1 - 65535 символов
Обязательно: Да
TableName Имя таблицы, в которой находится элемент.
Может содержать путь в иерархии каталогов вида path/to/table.

Тип: Строка
Длина: 3 - 255 символов
Шаблон: [a-zA-Z0-9_.-]+
Обязательно: Да
ConditionExpression Условие для замены элемента. Метод обработает только в том случае, если условие выполнится.
Условие состоит из:
  • Функции: attribute_exists | attribute_not_exists | attribute_type | contains | begins_with | size. Имена чувствительны к регистру.
  • Оператора сравнения: = | <> | < | > | <= | >= | BETWEEN | IN.
  • Логического оператора: AND | OR | NOT.

Тип: Строка
Обязательно: Нет
ExpressionAttributeNames Заполнитель (placeholder), который можно использовать в выражении вместо имени атрибута. Заполнитель должен начинаться с символа решетки #.
В каких случаях это может пригодиться:
  • Если нужно указать атрибут, имя которого конфликтует с зарезервированным словом.
  • В качестве переменной, если имя атрибута используется в выражении несколько раз.
  • Для предотвращения неправильной интерпретации специальных символов в имени атрибута.
Например, имя атрибута Percentile конфликтует с зарезервированным словом, и его нельзя в явном виде использовать в выражении. Чтобы обойти эту проблему, нужно в параметре ExpressionAttributeNames указать заполнитель: {"#P":"Percentile"}. И затем вместо настоящего имени атрибута использовать #P.

Тип: Строка
Длина: 1 - 65535 символов.
Обязательно: Нет
ExpressionAttributeValues Заполнитель (placeholder), который можно использовать в выражении вместо значения атрибута, аналогично ExpressionAttributeNames. Заполнитель должен начинаться с символа двоеточия :.
Например, нужно проверить, было ли значение атрибута ProductStatus одним из следующих: Available | Backordered | Discontinued. Для этого сначала объявить заполнители : { ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, ":disc":{"S":"Discontinued"} }. А потом их можно использовать в выражении: ProductStatus IN (:avail, :back, :disc)

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

Тип: Строка
Возможные значения: TOTAL | NONE
Обязательно: Нет
ReturnValues Используется, если нужно получить атрибуты элемента до изменения.
Возможные значения:
  • NONE — не возвращать атрибуты (по умолчанию)
  • ALL_OLD — вернуть все атрибуты в том виде, в котором они были до изменения

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

Ответ

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

{
   "Attributes": { 
      "string" : { 
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [ 
            "AttributeValue"
         ],
         "M": { 
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "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
   }
}

Параметры

Параметр Описание
Attributes Ассоциативный массив типа AttributeValue, который содержит значения атрибутов до изменения.
Возвращается только в том случае, если в запросе был указан параметр ReturnValues со значением ALL_OLD.

Тип: Ассоциативный массив типа AttributeValue
Длина: 1 - 65 535 символов.
ConsumedCapacity Единицы мощности, потребленные операцией удаления.
Возвращается только в том случае, если в запросе был указан параметр ReturnConsumedCapacity со значением TOTAL.

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

Ошибки

Параметр Описание
ConditionalCheckFailedException Невозможно оценить условие, указанное в операции.

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

Код состояния HTTP: 500
ItemCollectionSizeLimitExceededException Коллекция элементов слишком велика. Это исключение возвращается только для таблиц с одним или несколькими локальными вторичными индексами.

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

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

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

Код состояния HTTP: 400
TransactionConflictException Операция отклонена, так как для элемента выполняется другая транзакция.

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

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

Предыдущая
ListTables
Следующая
Query