ПланФикс API project.getList — различия между версиями

Материал из ПланФикс
Перейти к: навигация, поиск
 
(не показано 14 промежуточных версий 4 участников)
Строка 1: Строка 1:
 +
{{#seo:
 +
|title=ПланФикс API project.getList
 +
|titlemode=append
 +
|keywords=планфикс, проекты, апи, api
 +
|description=ПланФикс API project.getList
 +
}}
 +
 
Функция для получения списка проектов. Формат запроса:
 
Функция для получения списка проектов. Формат запроса:
 
<source lang="xml">
 
<source lang="xml">
Строка 16: Строка 23:
 
     <id></id>
 
     <id></id>
 
   </client>
 
   </client>
 +
  <filters>
 +
    <filter>
 +
      <type></type>
 +
      <operator></operator>
 +
      <value></value>
 +
      <field></field>
 +
      ...
 +
    </filter>
 +
    ...
 +
  </filters>
 
   <signature></signature>
 
   <signature></signature>
 
</request>
 
</request>
Строка 32: Строка 49:
 
|sortType ||enum ||тип сортировки ||не обязательный параметр. список допустимых значений смотри в разделе [[ПланФикс API:Типы сортировок для проектов|типы сортировок для проектов]]
 
|sortType ||enum ||тип сортировки ||не обязательный параметр. список допустимых значений смотри в разделе [[ПланФикс API:Типы сортировок для проектов|типы сортировок для проектов]]
 
|-
 
|-
−
|pageCurrent || int|| постраничная навигация ||не обязательный параметр. значения меньше 1 будут инициировать процедуру подсчета количества элементов.
+
|pageCurrent || int|| постраничная навигация ||не обязательный параметр. значение меньше 1 или отсутствие этого параметра будут инициировать процедуру подсчета количества элементов.
 
|-
 
|-
−
|pageSize ||int || количество выдаваемых значений в результате. не может превышать значение '''50''' ||не обязательный параметр. если будет опущен, возьмется значение по умолчанию.
+
|pageSize ||int || количество выдаваемых значений в результате. не может превышать значение '''100''' ||не обязательный параметр. если будет опущен, возьмется значение по умолчанию.
 
|-
 
|-
 
|client || || ||не обязательный параметр
 
|client || || ||не обязательный параметр
 
|-
 
|-
 
|client.id ||int || идентификатор контрагента, выступает в качестве фильтра ||
 
|client.id ||int || идентификатор контрагента, выступает в качестве фильтра ||
 +
|-
 +
|filters || || дополнительные сложные фильтры || перечень и формат допустимых значений смотри в разделе [[ПланФикс API:Фильтры проектов|фильтры проектов]]
 
|-
 
|-
 
|signature ||string(32) || подпись ||
 
|signature ||string(32) || подпись ||
Строка 49: Строка 68:
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<response status="ok">
 
<response status="ok">
−
   <prejects count="count" totalCount="totalCount">
+
   <projects count="count" totalCount="totalCount">
 
     <project>
 
     <project>
 
       <id></id>
 
       <id></id>
Строка 62: Строка 81:
 
         <name></name>
 
         <name></name>
 
       </client>
 
       </client>
 +
      <group>
 +
        <id></id>
 +
        <name></name>
 +
      </group>
 +
      <parent>
 +
        <id></id>
 +
      </parent>
 +
      <template>
 +
        <id></id>
 +
      </template>
 
       <status></status>
 
       <status></status>
 
       <hidden></hidden>
 
       <hidden></hidden>
Строка 70: Строка 99:
 
       <isOverdued></isOverdued>
 
       <isOverdued></isOverdued>
 
       <isCloseToDeadline></isCloseToDeadline>
 
       <isCloseToDeadline></isCloseToDeadline>
 +
      <customData>
 +
        <customValue>
 +
          <field>
 +
            <id></id>
 +
            <name></name>
 +
          </field>
 +
          <value></value>
 +
          <text></text>
 +
        </customValue>
 +
        <customValue>
 +
          <!-- ... -->
 +
        </customValue>
 +
        <!-- ... -->
 +
      </customData>
 
     </project>
 
     </project>
 
     <!-- ... -->
 
     <!-- ... -->
−
   </prejects>
+
   </projects>
 
</response>
 
</response>
 
</source>
 
</source>
Строка 78: Строка 121:
 
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание  
 
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание  
 
|-
 
|-
−
|'''prejects''' || || корневой элемент, содержит список проектов ||
+
|'''projects''' || || корневой элемент, содержит список проектов ||
 
|-
 
|-
−
|'''prejects''' count ||int || количество узлов/проектов возвращенных в результате выполнения запроса ||
+
|'''projects''' count ||int || количество узлов/проектов возвращенных в результате выполнения запроса ||
 
|-
 
|-
−
|'''prejects''' totalCount||int ||количество проектов удовлетворяющих запросу ||
+
|'''projects''' totalCount||int ||количество проектов удовлетворяющих запросу ||
 
|-
 
|-
 
|project || || корневой элемент, описывающий проект в списке ||
 
|project || || корневой элемент, описывающий проект в списке ||
Строка 100: Строка 143:
 
|client || || контрагент||
 
|client || || контрагент||
 
|-
 
|-
−
|client.id ||int || идентификатор проекта||
+
|client.id ||int || идентификатор контрагента||
 
|-
 
|-
 
|client.name ||string || имя контрагента ||
 
|client.name ||string || имя контрагента ||
 +
|-
 +
|group|| || группа проектов||
 +
|-
 +
|group.id ||int || идентификатор группы проектов||
 +
|-
 +
|group.name ||string || название группы проектов ||
 +
|-
 +
|parent|| || надпроект||
 +
|-
 +
|parent.id ||int || идентификатор надпроекта ||
 +
|-
 +
|template|| || шаблон||
 +
|-
 +
|template.id ||int || идентификатор шаблона ||
 
|-
 
|-
 
|status || enum||статус в котором находится сейчас проект || перечень допустимых значений для данного поля смотри в разделе [[ПланФикс API:Статусы проектов|статусы проектов]]
 
|status || enum||статус в котором находится сейчас проект || перечень допустимых значений для данного поля смотри в разделе [[ПланФикс API:Статусы проектов|статусы проектов]]
Строка 119: Строка 176:
 
|-
 
|-
 
|isCloseToDeadline ||bool ||осталось 25% времени до завершения или прошло 75% отведенного времени на выполнение его  ||
 
|isCloseToDeadline ||bool ||осталось 25% времени до завершения или прошло 75% отведенного времени на выполнение его  ||
 +
|-
 +
|customData ||  ||значения пользовательских полей задачи ||
 +
|-
 +
|customData.customValue.field.id ||  ||идентификатор пользовательского поля ||
 +
|-
 +
|customData.customValue.field.name||  ||название пользовательского поля ||
 +
|-
 +
|customData.customValue.value ||  ||значение пользовательского поля ||
 +
|-
 +
|customData.customValue.text ||  ||текстовое значение пользовательского поля ||
 
|-
 
|-
 
|}
 
|}
 
Атрибут '''totalCount''' у элемента '''projects''' показывает сколько всего может быть возвращено данным запросом проектов. Это позволяет избежать дополнительный запрос на полный подсчет количества проектов. Если требуется узнать только количество элементов, достаточно послать запрос с параметром '''pageCurrent'''=0.
 
Атрибут '''totalCount''' у элемента '''projects''' показывает сколько всего может быть возвращено данным запросом проектов. Это позволяет избежать дополнительный запрос на полный подсчет количества проектов. Если требуется узнать только количество элементов, достаточно послать запрос с параметром '''pageCurrent'''=0.
  
−
Пустой ответ не '''генерирует ошибку'''. Если в результирующую выборку не попадают никакие проекты, то ответ будет иметь следующую форму?
+
Пустой ответ не '''генерирует ошибку'''. Если в результирующую выборку не попадают никакие проекты, то ответ будет иметь следующую форму:
 
<source lang="xml">
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<response status="ok">
 
<response status="ok">
−
   <prejects count="0" totalCount="0"></prejects>
+
   <projects count="0" totalCount="0"></projects>
 
</response>
 
</response>
 
</source>
 
</source>
Строка 138: Строка 205:
 
</response>
 
</response>
 
</source>
 
</source>
−
{| class="wikitable" style="margin-top: 1em; width:100% "
+
 
−
!width="50"|Значение ''code'' !! Расшифровка
 
−
|-
 
−
|align="center"| 0000|| неизвестная ошибка
 
−
|-
 
−
|}
 
  
 
== Перейти ==
 
== Перейти ==
−
*[[ПланФикс API]]
 
 
*[[ПланФикс API:Проекты]]
 
*[[ПланФикс API:Проекты]]
 +
*[[Коды ошибок]]
 +
*[[Список функций]]

Текущая версия на 07:45, 16 июля 2018

Функция для получения списка проектов. Формат запроса: 

<?xml version="1.0" encoding="UTF-8"?>
<request method="project.getList">
  <account></account>
  <sid></sid>
  <user>
    <id></id>
  </user>
  <target></target>
  <status></status>
  <sortType></sortType>
  <pageCurrent></pageCurrent>
  <pageSize></pageSize>
  <client>
    <id></id>
  </client>
  <filters>
    <filter>
      <type></type>
      <operator></operator>
      <value></value>
      <field></field>
      ...
    </filter>
    ...
  </filters>
  <signature></signature>
</request>
Название Тип Значение Примечание
user пользователь ПланФикса не обязательный параметр. задается для того чтоб посмотреть проекты в которых принимает участие указанный пользователь. этот параметр должен задаваться только в том случае, если выполняется запрос от учетной записи с админ правами
user.id int идентификатор пользователя
target enum фильтр по вкладкам не обязательный параметр. список допустимых значений смотри в разделе фильтр вкладки для проектов
status enum фильтр по статусу не обязательный параметр. перечень допустимых значений для данного поля смотри в разделе статусы проектов
sortType enum тип сортировки не обязательный параметр. список допустимых значений смотри в разделе типы сортировок для проектов
pageCurrent int постраничная навигация не обязательный параметр. значение меньше 1 или отсутствие этого параметра будут инициировать процедуру подсчета количества элементов.
pageSize int количество выдаваемых значений в результате. не может превышать значение 100 не обязательный параметр. если будет опущен, возьмется значение по умолчанию.
client не обязательный параметр
client.id int идентификатор контрагента, выступает в качестве фильтра
filters дополнительные сложные фильтры перечень и формат допустимых значений смотри в разделе фильтры проектов
signature string(32) подпись

Все параметры, за исключением account, sid, signature не являются обязательными. Если опустить параметр user, то будет получен список проектов доступных для текущего пользователя, необходимо помнить что только администраторы могут смотреть проекты других участников.

Ответ: 

<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <projects count="count" totalCount="totalCount">
    <project>
      <id></id>
      <title></title>
      <description></description>
      <owner>
        <id></id>
        <name></name>
      </owner>
      <client>
        <id></id>
        <name></name>
      </client>
      <group>
        <id></id>
        <name></name>
      </group>
      <parent>
        <id></id>
      </parent>
      <template>
        <id></id>
      </template>
      <status></status>
      <hidden></hidden>
      <hasEndDate></hasEndDate>
      <endDate></endDate>
      <beginDate></beginDate>
      <taskCount></taskCount>
      <isOverdued></isOverdued>
      <isCloseToDeadline></isCloseToDeadline>
      <customData>
        <customValue>
          <field>
            <id></id>
            <name></name>
          </field>
          <value></value>
          <text></text>
        </customValue>
        <customValue>
          <!-- ... -->
        </customValue>
        <!-- ... -->
      </customData>
    </project>
    <!-- ... -->
  </projects>
</response>
Название Тип Значение Примечание
projects корневой элемент, содержит список проектов
projects count int количество узлов/проектов возвращенных в результате выполнения запроса
projects totalCount int количество проектов удовлетворяющих запросу
project корневой элемент, описывающий проект в списке
id int идентификатор проекта
title string название проекта
description string описание проекта
owner владелец/создатель проекта
owner.id int идентификатор пользователя
owner.name string имя пользователя, создавшего проект
client контрагент
client.id int идентификатор контрагента
client.name string имя контрагента
group группа проектов
group.id int идентификатор группы проектов
group.name string название группы проектов
parent надпроект
parent.id int идентификатор надпроекта
template шаблон
template.id int идентификатор шаблона
status enum статус в котором находится сейчас проект перечень допустимых значений для данного поля смотри в разделе статусы проектов
hidden bool скрытый
hasEndDate bool признак того, что для проекта установлена дата окончания
endDate DateTime дата окончания проекта установлена, только при hasEndDate = true
beginDate DateTime дата создания проекта
taskCount int количество задач в проекте
isOverdued bool признак того, что проект просрочен
isCloseToDeadline bool осталось 25% времени до завершения или прошло 75% отведенного времени на выполнение его
customData значения пользовательских полей задачи
customData.customValue.field.id идентификатор пользовательского поля
customData.customValue.field.name название пользовательского поля
customData.customValue.value значение пользовательского поля
customData.customValue.text текстовое значение пользовательского поля

Атрибут totalCount у элемента projects показывает сколько всего может быть возвращено данным запросом проектов. Это позволяет избежать дополнительный запрос на полный подсчет количества проектов. Если требуется узнать только количество элементов, достаточно послать запрос с параметром pageCurrent=0.

Пустой ответ не генерирует ошибку. Если в результирующую выборку не попадают никакие проекты, то ответ будет иметь следующую форму: 

<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <projects count="0" totalCount="0"></projects>
</response>

В противном случае будет возвращен ответ с ошибкой: 

<?xml version="1.0" encoding="UTF-8"?>
<response status="error">
  <code></code>
</response>


Перейти

Источник — «http://planfix.ru/wiki/index.php?title=ПланФикс_API_project.getList&oldid=15513»