> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge-ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/use-cases/collection/rabota-s-kollekciei-v-oz-api.md). # Работа с коллекцией в Oz API В этой статье рассказывается, как создать коллекцию методами API, как добавить в нее персону и фотографии, как потом все это удалить, а также удалить саму коллекцию. Все это можно также сделать [через веб-консоль](/oz-knowledge-ru/rukovodstva/rukovodstvo-polzovatelya/oz-webui/blacklist.md#sozdanie-chernogo-spiska), однако здесь мы описываем только соответствующие методы API. > Коллекция в Oz API — это база фотографий лиц (персон), которые используются в анализе Collection для сравнения с лицом человека с только что снятого фото или видео. > Персона — это сущность в коллекции, соответствующая одному человеку. Для одной персоны может быть загружено несколько фотографий. ### Как создать коллекцию Коллекция создается в рамках определенной компании, таким образом, для добавления новой коллекции необходим идентификатор компании `company_id`. Если вы его не знаете, найдите компанию поиском с помощью метода `GET /api/companies/?search_text=test`, где test — наименование компании или его часть. Сохраните полученный `company_id`. Для создания коллекции вызовите метод `POST /api/collections/`. В теле запроса укажите название своей коллекции (alias) и `company_id` нужной компании, как показано ниже: ```json { "alias": "blacklist", "company_id": "your_company_id" } ``` В ответе на запрос будет идентификатор коллекции `collection_id`. Он понадобится на следующем шаге. ### Как добавить персону или фото в коллекцию Для добавления новой персоны в коллекцию вызовите метод `POST /api/collections/{{collection_id}}/persons/`, где `collection_id` — идентификатор коллекции из предыдущего шага. В запросе передайте фото персоны (или несколько фото). В Payload укажите соответствующие фото [теги](/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/media-tags.md#tegi-fotofailov), как показано ниже. ```json { "media:tags": { "image1": [ "photo_selfie", "orientation_portrait" ] } } ``` В ответе вам придет идентификатор персоны `person_id` - это идентификатор отдельного человека в коллекции. В этом же запросе через payload можно добавить данные о персоне: ```json "person:meta_data": { "person_info": { "first_name": "John", "middle_name": "Jameson", "last_name": "Doe" } }, ``` Вы также можете загрузить дополнительные фото персоны после ее добавления: используйте метод `POST {{host}}/api/collections/{{collection_id}}/persons/{{person_id}}/images/` с соответствующим `person_id`. Тело запроса заполните так же, как для метода `POST /api/collections/{{collection_id}}/persons/`. Чтобы получить информацию о всех персонах в коллекции, вызовите метод `GET /api/collections/{{collection_id}}/persons/`. Если вам нужен список фотографий для отдельной персоны, воспользуйтесь методом `GET /api/collections/{{collection_id}}/persons/{{person_id}}/images/`. Обратите внимание: для каждого фото будет указан идентификатор фото `person_image_id` — он потребуется вам, например, для удаления фото. ### Как удалить фото или персону из коллекции Чтобы удалить персону со всеми соответствующими ей фотографиями, используйте метод `DELETE /api/collections/{{collection_id}}/persons/{{person_id}}`, указав идентификаторы коллекции и персоны. Все фото этой персоны удалятся автоматически. Персону нельзя удалить, если с ней связаны анализы — то есть если эта персона участвовала в анализе Black list и с ней были найдены совпадения. Для удаления такой персоны сперва нужно удалить соответствующие анализы методом `DELETE /api/analyses/{{analysis_id}}` (потребуется `analysis_id` анализа collection (Black list)). Для удаления всех связанных с коллекцией анализов запросите список всех папок с анализом Black list: call `GET /api/folders/?analyse.type=COLLECTION`. Для каждой папки из списка (`GET /api/folders/{{folder_id}}/`), найдите `analysis_id` нужного анализа, а затем удалите анализ — `DELETE /api/analyses/{{analysis_id}}`. Для удаления определенной фотографии той или иной персоны вызовите метод `DELETE /api/collections/{{collection_id}}/persons/{{person_id}}/images/{{person_image_id}}` и укажите идентификаторы коллекции, персоны, фотографии. ### Как удалить коллекцию целиком Перед удалением коллекции нужно удалить информацию о всех входящих в нее персонах, а затем стереть саму коллекцию с помощью метода `DELETE /api/collections/{{collection_id}}/`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/use-cases/collection/rabota-s-kollekciei-v-oz-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.