> 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.