updateAttributes
Compatible con API v20 +
Categoría
| Modificación de metadatos |
Descripción
| Actualice un conjunto de atributos existentes, sus valores de atributo y sus propiedades. Se pueden actualizar varios atributos con varios valores de atributo en una llamada. Si se realiza correctamente, la API devuelve detalles de los atributos que se han actualizado/creado. Si la API falla, se devuelve una lista completa de errores y sus causas. |
Permisos obligatorios para invocar
| Informes modelo |
Parámetros obligatorios bajo petición
| Credenciales |
La solicitud de este método contiene una etiqueta de credenciales para identificar y autorizar al usuario que llama. El usuario debe tener el "Modelo" Concepto: conjuntos de permisos y el permiso necesario para administrar los atributos que se están actualizando.
Recomendación: invoque exportAttributes para recuperar
Adaptive Planning
IDs de atributo necesarios para su solicitud de updateAttributes Haga todo lo posible por minimizar el tiempo entre las llamadas a exportAttributes y las llamadas a updateAttributes.HTTP | Descripción |
|---|---|
Method
| Post
|
Content-Type
| text/xml |
Ejemplo de rotación
curl -H "Content-Type: text/xml" -d @C:/temp/updateAttributes.xml -X POST https://api.adaptiveplanning.com/api/v20
contenido de updateAttributes.xml
Formato de solicitud
Update a set of existing attributes and their attribute values, and their <?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <attributes proceedWithWarnings="0"> <attribute id="13" name="AP Eligible" type="account" keepSorted="1"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> </attribute> </attributes> </call>
Para cargas útiles grandes, puede publicar archivos XML comprimidos (en zip). Descubra cómo hacerlo aquí.
Se aplican las siguientes condiciones a updateAttributes:
- Los atributos se identifican para su actualización mediante su número de ID interno.
- Para crear nuevos atributos, asígneles una propiedad de ID en blanco o que falte.
- Puede mover un elemento existente (no nuevo) para que se convierta en elemento secundario de un elemento nuevo. Al hacerlo, se crea el nuevo elemento y se mueve el elemento existente debajo de él como elemento secundario.
Formato de solicitud para crear un nuevo atributo
Para crear un nuevo atributo,
AP Eligible
, deje el ID en blanco y proporcione su nombre y tipo.<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="" name="AP Eligible" type="account"> <attributeValue id="" name="No" /> <attributeValue id="" name="Yes"> <attributeValue id="" name="Full" /> <attributeValue id="" name="Partial" /> </attributeValue> </attribute> </attributes> </call>
Solicitud de creación de un nuevo atributo para una dimensión de lista
Para crear un nuevo atributo
Education Type
para una dimensión de lista, Education.
Los valores de atributo Technical
y su hijo, Tech1,
tienen IDs en blanco, lo que indica que son nuevos.
<?xml version="1.0" encoding="UTF-8"?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password" /> <attributes> <attribute id="" name="Education Type" type="dimension" listDimensionName="Education" keepSorted="1" importAutoCreateValues="1"> <attributeValue id="" name="Technical" description=""> <attributeValue id="" name="Tech1" description="" /> </attributeValue> <attributeValue id="" name="Management" description="" /> </attribute> </attributes> </call>
Formato de solicitud para crear un nuevo valor de atributo
future
por debajo de AP Eligible
atributo con id 13
y valor de atributo no
con id 118
, puede utilizar:<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="13"> <attributeValue id="118" > <attributeValue id="" name="future" /> </attributeValue> </attribute> </attributes> </call> To create a new attribute value, include its parent by its ID. For example, to add a new attribute value
Este método no cambia nada sobre el atributo.
id 13
. Crea un nuevo valor de atributo future
para atributo id 13
y convierte a su elemento principal en el valor de atributo no
. Todos los valores de atributo no mencionados de no
desplazarse al final de la lista de valores. Esto es el equivalente a "establecer el elemento principal" para el nuevo valor de atributo.Gestión de varios cambios de nombre en una sola llamada de updateAttributes
Se pueden realizar varios cambios de nombre de la misma entidad en un sistema remoto entre
updateAttributes
llamadas Los nombres de las entidades del sistema remoto pueden intercambiarse por los mismos ID de entidad. Cuándo updateAttributes
las llamadas tienen lugar después del intercambio de nombre, el updateAttributes
call gestiona estos cambios realizando un seguimiento de los ID en los cambios de nombre. La llamada también puede gestionar la introducción de un nuevo ID que utilice un nombre existente.Para que cada uno de los ejemplos sea correcto, el intercambio completo de IDs debe realizarse con los valores exclusivos.
Ejemplo 1: un simple intercambio de nombres en el sistema remoto.
To create a new attribute value, include its parent by its ID. For example, to add a new ID Unique Value New Unique Value 1 AA BB 2 BB AA
Ejemplo 2: una secuencia de 3 cambios de nombre en el sistema remoto.
ID Unique Value New Unique Value 1 AA BB 2 BB CC 3 CC AA
Ejemplo 3: una nueva entidad que utiliza un valor exclusivo existente.
ID Unique Value New Unique Value 4 AA 1 AA BB 2 BB Old BB
elemento de credenciales
| |||
Nombre de etiqueta
| credenciales | ||
Descripción
| Todas las llamadas a la API deben contener un único elemento de credenciales para identificar al usuario que invoca la API. A continuación, la llamada a la API se realiza como este usuario (cualquier pista de auditoría o historial de acciones en el sistema mostrará que este usuario ha realizado la acción) y, por lo tanto, el usuario debe tener los permisos necesarios para realizar la acción a fin de que la llamada a la API se lleve a cabo. correcta | ||
Atributos del elemento
| |||
Nombre de atributo
| ¿Obligatorio?
| Valor
| Ejemplo
|
inicio de sesión | Sí | El nombre de conexión del usuario que invoca el método API. Este usuario debe tener los permisos necesarios para invocar el método. | sampleuser@company.com |
contraseña | Sí | La contraseña del usuario que invoca el método API. | my_password |
configuración regional | No | Especifique la configuración regional que se utilizará para interpretar los números y las fechas de entrada, y para dar formato a los números y las fechas de salida (utilizando el separador de miles, los nombres de mes y el formato de fecha adecuados). La configuración regional también se utiliza para especificar el idioma en el que deben aparecer los mensajes del sistema en la respuesta. Si no se especifica, se utiliza en_US (inglés americano). | fr_FR |
instanceCode | No | Si el usuario especificado en las credenciales tiene acceso a más de una instancia de Adaptive Planning , este atributo se puede utilizar para especificar que el usuario tiene la intención de acceder a una instancia distinta a la instancia por defecto. Si no se especifica, se utilizará la instancia por defecto del usuario. Para determinar los códigos de instancia disponibles, utilice la API exportInstances. | MYINSTANCE1 |
Contenido del elemento
| |||
(ninguno) | |||
elemento de atributos
| |||
Nombre de etiqueta
| atributos | ||
Descripción
| Solo se permite una solicitud de elemento de atributos por carga útil. Contiene uno o varios elementos de atributo. | ||
Atributos del elemento
| |||
Nombre de atributo
| ¿Obligatorio?
| Valor
| Ejemplo
|
procedaWithWarnings | No | Solo se aplica cuando se cambian los valores principales de los atributos. Si hay avisos y procedaWithWarnings=0, el atributoAttributeValue no se actualizará. Defina procedaWithWarnings=1 para actualizar el atributoAttributeValue cuando haya avisos. Solo se aplica a type=account y type=level. ProceedWithWarnings=1 (a) el cambio de parentesco se realiza aunque el etiquetado de atributos de cuenta/nivel sea incompatible. (b) Todas las etiquetas de atributos de cuenta/nivel incompatibles se corregirán mediante el etiquetado de atributos del elemento principal. ProceedWithWarnings=0 genera un error si el cambio de parentesco del valor de atributo daría lugar a que la asignación de atributos de cuenta/nivel se vuelva incompatible. | 1 |
retainExistingOrder Disponible en API v27+ | No | RetainExistingOrder="1" indica que la API de updateAttributes debe ignorar el orden de los elementos en la carga útil XML y se conservará el orden definido existente. RetainExistingOrder="0" indica que la API de updateAttributes debe actualizar el orden de los elementos en función de la posición de la etiqueta en relación con otros elementos del mismo nivel en la carga útil XML. El indicador de preserveExistingOrder se ignora cuando el atributo tiene activado el indicador keepSorted. El valor por defecto de retainExistingOrder es "1". | 1 |
DisplayNameEnabled
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | displayNameEnabled=1 indica que updateAttribues debe respetar las propiedades de nombre de visualización de code , displayNameType y description cuando Activar nombre de visualización está activado para la instancia.displayNameEnabled=0 indica que la API updateAttributes debe seguir el contrato de la API anterior a la v30 aunque la opción Activar nombre de visualización esté activada para la instancia. La API updateAttributes ignora las propiedades de nombre de visualización. code , displayNameType y description .El valor por defecto de displayNameEnabled es "0". | 1 |
Contenido del elemento
| |||
Contiene uno o varios elementos de atributo. | |||
elemento de atributo
| |||
Nombre de etiqueta
| atributo | ||
Descripción
| Especifica un atributo para crear o actualizar. | ||
Atributos del elemento
| |||
Nombre de atributo
| ¿Obligatorio?
| Valor
| Ejemplo
|
ID | Sí | El número de ID de sistema interno para el atributo. | 16 |
nombre
Actualizado en API v30 | Sí | El nombre del atributo, tal como aparece en informes y hojas.
| Activo corriente |
código
Disponible en API v39+. | No | El código del atributo | Activo corriente |
displayNameType
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | Controla la visualización de los valores de atributo. Los valores posibles son NAME, CODE, NAME_CODE o CODE_NAME.
El valor por defecto es NAME cuando se deja en blanco o no se proporciona. Esta propiedad solo está disponible cuando la opción Activar nombre de visualización está activada para la instancia. | "CODE_NAME" |
importAutoCreateValues | No | "1" significa que los valores de atributo para este atributo se pueden crear mediante la importación, "0" (o no especificado) significa que no se pueden crear. | 1 |
tipo | No | Indica si el atributo es un atributo de nivel, de cuenta o de dimensión. Obligatorio para crear nuevos atributos que aún no existen en el sistema. El tipo no se puede cambiar mediante una operación de actualización. | cuenta |
listDimensionName | No | Indica si la dimensión es una dimensión de lista plana. Solo es aplicable cuando el atributo type=dimension. listDimensionName no se puede cambiar mediante una operación de actualización. | color |
keepSorted | No | "1" indica que los valores de este atributo siempre se ordenan alfabéticamente. "0" (o no especificado) significa que los valores de atributo se ordenan en función de su posición en la carga útil de la solicitud. El valor por defecto es "0" solo en la operación de creación cuando no se proporciona ningún valor. Si el XML contiene tanto el elemento principal como al menos un elemento del mismo nivel de un valor de atributo jerárquico no listado, el valor no listado se mueve al final de los elementos del mismo nivel enumerados durante la actualización (al reordenar los elementos secundarios del elemento principal, todos los elementos del mismo nivel enumerados van primero, en el orden en que se especifican en el XML. Todos los elementos del mismo nivel que no figuran en la lista aparecen en último lugar, en el orden en el que ya están en el sistema). keepSorted se aplica a los elementos secundarios de cada valor de atributo principal. Cualquier cambio en los componentes de un nombre de visualización podría alterar el criterio de ordenación de los elementos, cuando Mantener orden está activado. | 1 |
shortName
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | El nombre corto del atributo. La longitud máxima de caracteres es 64.
Solo está disponible cuando la opción Activar nombre de visualización está activada para la instancia. | Activo |
descripción
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | La descripción del atributo. La longitud máxima de caracteres es 2048.
Valor por defecto: vacío Esta propiedad solo está disponible cuando la opción Activar nombre de visualización está activada para la instancia. | Activo |
Contenido del elemento
| |||
Uno o varios elementosAttributeValue. | |||
elementoAttributeValue
| |||
Nombre de etiqueta
| attributeValue | ||
Descripción
| Especifica los valores de atributo que se crearán o actualizarán. | ||
Atributos del elemento
| |||
Nombre de atributo
| ¿Obligatorio?
| Valor
| Ejemplo
|
ID | No | Identifica el valor de atributo. Si se deja en blanco, indica que la solicitud está creando un nuevo valor de atributo. | 24 |
código
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | El código exclusivo del valor de atributo.
| Sí |
nombre
Actualizado en API v30 | Sí | El nombre del valor de atributo, tal como aparece en hojas e informes. Cuando Activar nombre de visualización está activado para una instancia con API v30 o superior, el nombre permite valores duplicados. Cuando Activar nombre de visualización está desactivado para una instancia, el código no está disponible y el nombre debe ser exclusivo. Nombres de valor de atributo no válidos: estos nombres que terminan en (+) o (-) | Sí |
descripción | No | La descripción textual del valor de atributo. Valor por defecto: vacío El valor por defecto solo se utiliza en la operación de creación cuando no se proporciona ningún valor. | |
Contenido del elemento
| |||
Puede contener otro atributoAttributeValue. | |||
Formato de respuesta
<?xml version="1.0" encoding="UTF-8"?> <response success="true"> <messages> <message type="INFO">Attributes were saved successfully.</message> </messages> <output> <attributes> <attribute id="13" name="AP Eligible" type="account"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9" name="Corporate Discount" type="level"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> <attributeValue id="57" name="Not Available" /> <attributeValue id="55" name="TBD" /> </attribute> <attribute id="10" name="Tax Code" type="level"> <attributeValue id="146" name="TT-PYT" /> <attributeValue id="145" name="TT-TRE" /> </attribute> <attribute id="16" name="Industry" type="dimension" listDimensionName="Education"> <attributeValue id="335" name="Apparel"> <attributeValue id="354" name="Mens Apparel" /> <attributeValue id="355" name="Shoes" /> <attributeValue id="356" name="Womens Apparel" /> </attributeValue> </attribute> </attributes> </output> </response>
elemento de resultado
| |
Nombre de etiqueta
| salida |
Atributos del elemento
| |
(ninguno) | |
Contenido del elemento
| |
Un solo elemento de atributos obligatorios. Este contenedor de salida es estándar en todas las respuestas de API e incluye la salida válida de cualquier llamada API correcta. | |
elemento de atributos
| |||
Nombre de etiqueta
| atributos | ||
Descripción
| Contenedor para cero o más elementos de atributo. Las etiquetas se colocan en orden en función de la solicitud de entrada. | ||
Atributos del elemento
| |||
Nombre de atributo
| ¿Obligatorio?
| Valor
| Ejemplo
|
procedaWithWarnings | No | El valor deprocWithWarnings proporcionado en la solicitud de API. | 1 |
retainExistingOrder | No | updateAttributes=0 actualiza el criterio de ordenación en función del contenido de la carga útil XML. updateAttributes=1 conserva el criterio de ordenación existente. | 1 |
displayNameEnabled
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | displayNameEnabled=1 indica que updateAttributes debe respetar las propiedades de nombre de visualización de code , displayNameType y description cuando Activar nombre de visualización está activado para la instancia.displayNameEnabled=0 indica que la API updateAttribues debe seguir el contrato de API anterior a 2021.42 aunque la opción Activar nombre de visualización esté activada para la instancia. La API updateAttribues ignora las propiedades de nombre de visualización code , displayNameType y description .El soporte para displayNameEnabled comenzó en 2021.42. El valor por defecto de displayNameEnabled es "0". | 1 |
Contenido del elemento
| |||
Uno o varios elementos de atributo | |||
elemento de atributo
| |||||
Nombre de etiqueta | atributo | ||||
Descripción
| Representa un solo atributo que se devuelve en la respuesta a una llamada a la API de updateAttributes. | ||||
Atributos del elemento
| |||||
Nombre de atributo
| ¿Obligatorio?
| Valor
| Ejemplo
| ||
ID | Sí | El número de ID de sistema interno para el atributo. | 16 | ||
nombre | Sí | El nombre del atributo, tal como aparece en informes y hojas. | Activo corriente | ||
código
Disponible en API v39+. | Sí | El código del atributo. | Activo corriente | ||
shortName | El nombre corto del atributo. La longitud máxima de caracteres es 2048. | Activo | |||
displayNameType
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | Controla la visualización de los valores de atributo. Los valores posibles son NAME, CODE, NAME_CODE o CODE_NAME.
El valor por defecto es NAME cuando se deja en blanco o no se proporciona. Esta propiedad solo está disponible cuando la opción Activar nombre de visualización está activada para la instancia. | CODE_NAME | ||
importAutoCreateValues | No | "1" significa que los valores de atributo para este atributo se pueden crear mediante la importación, "0" (o no especificado) significa que no se pueden crear. | 1 | ||
tipo | Sí | El tipo del atributo. Será "account" si el atributo es para una cuenta, "level" si el atributo es para un nivel o "dimension" si el atributo es para una dimensión. | cuenta | ||
listDimensionName | No | El nombre de la dimensión de lista si el atributo es del tipo "dimensión". | Estudios | ||
descripción | No | La descripción textual del atributo, si la hay, tal como se ha introducido en Administración de atributos | Total de activos corrientes | ||
keepSorted | Sí | "1" indica que los valores de este atributo siempre se ordenan alfabéticamente. "0" (o no especificado) significa que los valores de atributo se ordenan en función de su posición en la carga útil de la solicitud. Si el XML contiene tanto el elemento principal como al menos un elemento del mismo nivel de un valor de atributo jerárquico no listado, el valor no listado se mueve al final de los elementos del mismo nivel enumerados durante la actualización (al reordenar los elementos secundarios del elemento principal, todos los elementos del mismo nivel enumerados van primero, en el orden en que se especifican en el XML. Todos los elementos del mismo nivel que no figuran en la lista aparecen en último lugar, en el orden en el que ya están en el sistema). keepSorted se aplica a los elementos secundarios de cada valor de atributo principal. | 1 | ||
estado | Sí | El estado del valor de atributo después de la actualización. En el caso de los avisos y los errores, el elemento de mensaje incluye el contenido del mensaje. El estado actualizado no devuelve ningún contenido de mensaje.
| Actualizado | ||
mensaje | No | El mensaje de error de la entrada de atributo. | El atributo Sector está duplicado en la carga útil o ya existe en el sistema con el ID 8 | ||
Contenido del elemento
| |||||
Cero o más elementosAttributeValue opcionales. Cada elemento de valor de atributo adjunto representa un "valor de atributo raíz" en el atributo, un valor que no tiene ningún valor principal. | |||||
elementoAttributeValue
| |||
Nombre de etiqueta
| attributeValue | ||
Descripción
| Representa un valor de miembro único de un atributo que se devuelve en la respuesta a una llamada a la API de updateAttributes. | ||
Atributos del elemento
| |||
Nombre de atributo
| ¿Obligatorio?
| Valor
| Ejemplo
|
ID | Sí | El número de ID de sistema interno para este valor de miembro del atributo. | 34 |
código
Solo está disponible en API v30+ para instancias que activan el nombre de visualización. | No | El código exclusivo del valor de atributo. | Disponibles |
nombre | Sí | La etiqueta del valor de miembro del atributo que se muestra en la página de administración de atributos. | Disponibles |
shortName | No | El nombre corto del valor de atributo. | Prom. |
descripción | No | La descripción del valor de atributo. Valor por defecto: vacío El valor por defecto solo se utiliza en la operación de creación cuando no se proporciona ningún valor. | |
propogateToDescendants | No | Indica si los cambios se propagan a los elementos secundarios de este nivel. 0 para no, 1 para sí. | 0 |
estado | Sí | El estado del atributo después de la actualización. En el caso de los avisos y los errores, el elemento de mensaje incluye el contenido del mensaje. El estado actualizado no devuelve ningún contenido de mensaje.
| actualizado |
mensaje | No | El mensaje de error de una entrada de valor de atributo no válida. | |
Contenido del elemento
| |||
Cero o más elementosAttributeValue opcionales. Cada elemento de valor de atributo adjunto representa un "valor de atributo secundario" de este valor de atributo, cuyos miembros se agrupan implícitamente en este valor. | |||