17.4.13. Performing standard operations

<< Prev   Next >>

This section contains examples of performing some standard operations while handling data using the standard OData interface.

17.4.13.1. Handling one object

17.4.13.1.1. Reading data

To get information about an entity, use the canonical URL of the entity. Reading is done with a GET request.

Example of reading a reference object:

http://host/base/odata/standard.odata/Catalog_Goods(guid'value')

Example of reading a record set of a subordinate information register:

http://host/base/odata/standard.odata/InformationRegister_InitialPrices(Recorder_Key=guid'value')

In this example, guid'value' identifies the document that generated a information register record.

Example of reading an information register record:

http://host/base/odata/standard.odata/InformationRegister_ReceiptPrices_RecordType(Product_Key=guid'value', PriceType="Receipt")

Example of reading a particular document row:

http://host/base/odata/standard.odata/Document_GoodsConsumption_Goods(Ref_Key=guid'value', LineNumber=1)

Reading the SliceLast virtual table of the CurrencyRates information register (with filter by the MainCurrency dimension of the CatalogRef.Currencies type) looks as follows:

Example of reading an independent information register:

http://host/base/odata/standard.odata/InformationRegister_CurrencyRates/SliceLast?Condition=Currency/MainCurrency_Key eq guid'value'

Example of reading a subordinate information register (add _RecordType to the register name):

http://host/base/odata/standard.odata/InformationRegister_CurrencyRates_RecordType/SliceLast?Condition=Currency/MainCurrency_Key eq guid'value'

In this example, guid'value' identifies the Currencies catalog item, by the value of which the filter is performed.

Example of retrieving the account balance from the accounting register with a particular counterparty condition:

http://host/base/odata/standard.odata/AccountingRegister_SelfSupporting/Balance(AccountCondition='Account_Key eq guid'value1'',Condition='ExtDimension1 eq cast(guid'value2', 'Catalog_Counterparties')',ExtraDimensions='value3')?$format=json

In this example:

• guid'value1'. UUID of an item of the chart of accounts.
• guid'value2'. UUID of an item of the ExtDimensionTypesSelfSupporting chart of characteristic types with the CatalogRef.Counterparties value type.
• 'value3'. UUID of an item of the Counterparties catalog.

Here is an example of how to get an accounting register record set by recorder:

http://host/base/odata/standard.odata/AccountingRegister_AccountingRegisterWithCorrespondence(guid'value')?$format=json

In this example:

• guid'value'. UUID of the recorder that recorded the AccountingRegisterWithCorrespondence accounting register record set.

As a result, you will get a JSON document that contains the accounting register record set. In this document, the Recorder_Key property will match the guid’value’ value that was passed in the request.

17.4.13.1.2. Creating objects

To create an object, use a POST request using the URL of the set of entities and passing a document (in the supported format), which contains the values of the fields of the object to be created, in the request body. If the passed document contains properties that the object to be created does not have, then these properties are ignored.

The following is an example of creating an item of the Goods catalog and the response of the standard OData interface after the successful completion of the operation.

Example of a POST request (atom format):

POST http://host/base/odata/standard.odata/Catalog_Goods HTTP/1.1
User Agent: Fiddler
Host: host
Content Length: 981

<entry>
<category term="StandardODATA.Catalog_Goods" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
<title type="text"/>
<updated>2014-02-14T12:05:55</updated>
<author/>
<summary/>
<content type="application/xml">
<m:properties xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<d:DeletionMark>false</d:DeletionMark>
<d:Parent_Key>bbb079ae-8c51-11db-a9b0-00055d49b45e</d:Parent_Key>
<d:IsFolder>false</d:IsFolder>
<d:Code>000000800</d:Code>
<d:Description>FlipFlops</d:Description>
<d:SKU>SL56X</d:SKU>
<d:Supplier_Key>086715b0-f348-11db-a9c5-00055d49b45e</d:Supplier_Key>
<d:Type>Product</d:Type>
<d:Barcode/>
<d:Description>&lt;html&gt;Beach flip flops&lt;/html&gt;</d:Description>
</m:properties>
</content>
</entry>

Example of a standard OData interface response:

HTTP/1.1 201 Created
Content Length: 2705
Content Type: application/atom+xml;type=entry;charset=utf 8
Location: http://host/base/odata/standard.odata/Catalog_Goods(guid'41aa6331-954f-11e3-814b-005056c00008')
Server: Microsoft IIS/7.5
DataServiceVersion: 3.0
X Powered By: ASP.NET
Date: Fri, Feb 14, 2014 08:18:36 GMT

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<id>http://host/base/odata/standard.odata/Catalog_Goods(guid'41aa6331-954f-11e3-814b-005056c00008')</id>
<category term="StandardODATA.Catalog_Goods" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
<title type="text"/>
<updated>2014-02-14T12:18:36</updated>
<author/>
<summary/>
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/PictureFile"
href="Catalog_Goods(guid'41aa6331-954f-11e3-814b-005056c00008')/PictureFile"
type="application/atom+xml;type=entry;charset=utf-8"
title="PictureFile"/>
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Parent"
href="Catalog_Goods(guid'41aa6331-954f-11e3-814b-005056c00008')/Parent"
type="application/atom+xml;type=entry;charset=utf-8"
title="Parent"/>
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Supplier"
href="Catalog_Goods(guid'41aa6331-954f-11e3-814b-005056c00008')/Supplier"
type="application/atom+xml;type=entry;charset=utf-8"
title="Supplier"/>
<link rel="edit"
href="Catalog_Goods(guid'41aa6331-954f-11e3-814b-005056c00008')"
title="edit link"/>
<content type="application/xml">
<m:properties xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<d:Ref_Key>41aa6331-954f-11e3-814b-005056c00008</d:Ref_Key>
<d:DataVersion m:null="true"/>
<d:Description>FlipFlops</d:Description>
<d:Code>000000800</d:Code>
<d:Parent_Key>bbb079ae-8c51-11db-a9b0-00055d49b45e</d:Parent_Key>
<d:IsFolder>false</d:IsFolder>
<d:DeletionMark>false</d:DeletionMark>
<d:SKU>SL56X</d:SKU>
<d:Supplier_Key>086715b0-f348-11db-a9c5-00055d49b45e</d:Supplier_Key>
<d:PictureFile_Key>00000000-0000-0000-0000-000000000000</d:PictureFile_Key>
<d:Type>Product</d:Type>
<d:Barcode/>
<d:Description>&lt;html&gt;Beach flip flops&lt;/html&gt;</d:Description>
<d:PictureFile_Key>00000000-0000-0000-0000-000000000000</d:PictureFile_Key>
<d:Parent_Key>bbb079ae-8c51-11db-a9b0-00055d49b45e</d:Parent_Key>
<d:Supplier_Key>086715b0-f348-11db-a9c5-00055d49b45e</d:Supplier_Key>
</m:properties>
</content>
</entry>

Example of a POST request (json format):

POST http://host/base/odata/standard.odata/Catalog_Goods HTTP/1.1
Accept: application/json
Accept Charset: UTF 8
User Agent: Fiddler
Content Type: application/json
Content Length: 2426

{
"DeletionMark":false,
"Parent_Key":"bbb079ae-8c51-11db-a9b0-00055d49b45e",
"IsFolder":false
"Code":"000000800",
"Description":"FlipFlops",
"SKU":"SL56X",
"Supplier_Key":"086715b0-f348-11db-a9c5-00055d49b45e",
"Type":"Product",
"Barcode":null,
"Description:"Beach flip flops"
}

17.4.13.1.3. Updating objects

To update an object, execute a PUT/PATCH request using the canonical URL of the entity (similar to a GET request to get an entity), passing an XML document (in atom format) or a JSON document (in json format) that contains entity property values in the request body. If the passed document contains properties that the object to be created does not have, then these properties are ignored.

In the case of a PATCH request, omitted entity properties will be ignored, that is, only those properties that are passed in the change request will be changed. For a PUT request, specify values of all properties of the entity to be updated.

When modifying an entity with a PUT request, when recording values of reference attributes, use the ReferenceAttributeName@odata.bind field where you should place entity URI (in a shortened version, only the path fragment after standard.odata).

Example:

PUT http://host /base/odata/standard.odata/Document_Document(guid'19961ec3-3c5f-11e7-8785-50465da19fe4')?$format=json
{
"Date": "2015-01-01T12:01:07",
"Company@odata.bind": "Catalog_Companies(guid'298584b5-92e4-11e3-8bc3-0050568b1678')",
"Warehouse@odata.bind": http://host /base/odata/standard.odata/Catalog_Warehouses(guid'081bc346-2abc-13e4-a1bd 050568b1688')
…
}

The next example illustrates changing the Description attribute and the SalesAreas table components in the Stores catalog. Other catalog attributes are not used in this example. The example uses the json data format.

Example of a PATCH request:

PATCH http://host/base/odata/standard.odata/Catalog_Stores(guid'value')?$format=json HTTP/1.1

Host: host
Connection: keep alive
Accept: application/json
Content Length: 638

{
"odata.metadata": "http://host/base/odata/standard.odata/$metadata#Catalog_Stores/@Element",
"Description": "New store description",
"SalesAreas@odata.type" : "Collection(StandardODATA.Catalog_Stores_SalesAreas_RowType)"
"SalesAreas": [
{
"LineNumber": "1",
"Description": "Blue area",
"Square": 56,
"OpeningDate": "2015-01-01T00:00:00"
},
{
"LineNumber": "2",
"Description": "Red area",
"Square": 56,
"OpeningDate": "2015-06-13T11:45:41"
}
]
}

In this example, guid'value' identifies the Stores catalog item to be changed.

To change an accounting register record set, follow the steps:

1. Read the record set that you want to change. Use a GET request.
2. Modify the data returned by the previous request. That is, change the data in existing set records, add new records, and delete the existing ones.
3. Update the record set in the infobase. For this, use a PATCH request.

Let's take a closer look at the sequence of actions.

To get a record set, execute a GET request of the following type:

http://host/base/odata/standard.odata/AccountingRegister_AccountingRegisterWithCorrespondence(guid'value')?$format=json

In this example, the request is made to the AccountingRegisterWithCorrespondence accounting register. guid’value’ is a reference to the recorder that created the record set in the register.

As a result of the GET request, you will get the information of the following type:

Content-Type: application/json;charset=utf-8
Content-Length: X
{
"odata.metadata": "http://host/base/odata/standard.odata/$metadata#AccountingRegister_AccountingRegisterWithCorrespondence/@Element"
"Recorder_Key": "value",
"RecordSet": [
{
"Recorder_Key": "value",
…
}
]
}

In the above code snippet, value is the value of the reference to the recorder that was passed in the GET request.

When you modify the received data, generate a header of the data to record as follows:

{
"odata.type": "StandardODATA.AccountingRegister_AccountingRegisterWithCorrespondence_RowType",
"Recorder_Key": "value",
"RecordSet@odata.type": "Collection(StandardODATA.AccountingRegister_AccountingRegisterWithCorrespondence_RowType)",
"RecordSet": [
... // contents of the record set
]
}

In this data set:

• value. Value of the recorder reference.
• odata.type. Description of the type of data to be placed in the infobase.
• RecordSet@odata.type. Indicates the record set type (the RecordSet property).

In the record set, you can change properties of existing records, add new records, and delete existing records.

Once the record set is modified, update the information in the infobase. For this, use the following PATCH request:

http://host/base/odata/standard.odata/AccountingRegister_AccountingRegisterWithCorrespondence(guid'value')

The request body will be a JSON document that was prepared earlier based on the result of the GET request.

In the following example, you will see how to change the ShouldUseIntegration constant of the Boolean type. The example uses the json data format.

Example of a PATCH request:

PATCH http://host/base/odata/standard.odata/Constant_ShouldUseIntegration(guid'00000000-0000-0000-0000-000000000000')?$format=json
{
"Value": true,
}

17.4.13.1.4. Deleting objects

To delete an object, use a DELETE request using the canonical URL of the entity.

17.4.13.1.5. Optimistic data locking

To optimistically lock data, that is, to check that the data has not changed since it was read, use the If-Match header of the HTTP request associated with data modification (PATCH) or data deletion (DELETE). The header value must be the value of the DataVersion property, which was retrieved during the preliminary reading of the entity.

This feature works as follows:

• When an entity instance is requested, the DataVersion property is returned among others. When an entity set is requested, the DataVersion property is returned from each entity of the set.
• The client application must store this object version value and then use it in PATCH and DELETE requests by passing it in the If-Match header.
• If the value of the DataVersion property matches the value of the If-Match header on the request execution, the requested action takes place. Otherwise, the action is not performed, and the the 412 HTTP status is returned to the client.

17.4.13.1.6. Recording objects in data load mode

If you need to emulate a record, which is executed during operation of the data exchange feature (the DataExchange.Load = True property), while recording an object, use the 1C_OData-DataLoadMode HTTP header with the true value when you perform the relevant record operation.

17.4.13.1.7. Posting and unposting documents

To post a document, execute a POST request using the canonical URL of the entity (similar to a GET request to get an entity), specifying a specially generated URL suffix. In this case, the suffix will consist of the Post command and a parameter that indicates the document posting mode: http://host/base/odata/standard.odata/Document_GoodsConsumption(guid'value')/Post?PostingModeOperational=false.

To unpost a document, the suffix consists of the Unpost command without parameters.

17.4.13.2. Handling object collections

To get an entity set of any kind, execute a GET request using the following URL: http://host/base/odata/standard.odata/ExchangePlan_DataExhange.

To set a filter for the list to be received, use the $filter parameter, which is specified in the URL:

http://host/base/standard.odata/Document_Receipt?$filter=Priority eq 1

Accessing the virtual register table looks as follows (on the example of the BalanceAndTurnovers virtual table of the Inventory accumulation register):

http://host/base/odata/standard.odata/AccumulationRegister_Inventory/BalanceAndTurnovers(StartPeriod=datetime'2014 01 01', EndPeriod=datetime'2014 02 01', Condition='Product_Key eq guid'value'')

You can also use the $top and $select parameters to limit the entity set.

17.4.13.3. Handling exchange plans

17.4.13.3.1. Generating exchange messages

To generate an exchange message, execute a POST request using the following URL: http://host/base/odata/standard.odata/SelectChanges?<params>. Specify the following parameters:

• DataExchangePoint. Must contain the canonical URL of the entity of the required exchange plan item.
• MessageNo. Must contain the data exchange message number that will be generated as a result of this call.

As a result, the full URL for generating an exchange message will look as follows: http://host/base/odata/standard.odata/SelectChanges?DataExchangePoint='http://host/base/odata/standard.odata/ExchangePlan_DataExchange(guid'value')'&MessageNo=34.

This will result in a list of changes that are to be passed to another node as an atom-feed stream. Each item will be presented in the atom-entry format, and deleted items will be presented in the atom-deleted-entry format (RFC 6721, https://datatracker.ietf.org/doc/html/rfc6721).

17.4.13.3.2. Notification of changes receipt

To notify the server that the exchange message has been successfully received, execute a POST request using the following URL: http://host/base/odata/standard.odata/ NotifyChangesReceived?<params>. Specify the following parameters:

• DataExchangePoint. Must contain the canonical URL of the entity of the required exchange plan item.
• MessageNo. Must contain the number of the data exchange message whose receipt confirmation must be commited.

As a result, the full URL for confirming the exchange message receipt will look as follows: http://host/base/odata/standard.odata/NotifyChangesReceived?DataExchangePoint='http://host/base/odata/standard.odata/ExchangePlan_DataExchange(guid'value')'&MessageNo=34.

<< Prev   Next >>