Skip to content

Commit 5589cc7

Browse files
tomglvngLevFlavien
tomglvng
authored and
LevFlavien
committed
Add Product UUID resources
1 parent 5b94bbb commit 5589cc7

File tree

2 files changed

+315
-1
lines changed

2 files changed

+315
-1
lines changed

‎content/php-client/resources/products/products-uuid.md

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
### Product UUID
2+
3+
::: info
4+
The following endpoints are largely the same as for [products](/php-client/resources.html#products-uuid). The difference? Here, you can query, create or update products identified by its uuid. More information [here](/content/getting-started/from-identifiers-to-uuid-7x/welcome.md).
5+
:::
6+
7+
#### Get a product
8+
::: php-client-availability versions=10.0 editions=CE,EE
9+
10+
```php
11+
$client = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
12+
13+
/*
14+
* Returns an array like this:
15+
* [
16+
* 'identifier' => 'top',
17+
* 'enabled' => true,
18+
* 'family' => 'tshirt',
19+
* 'categories' => ['summer_collection'],
20+
* 'groups' => [],
21+
* 'parent' => null,
22+
* 'values' => [
23+
* 'name' => [
24+
* [
25+
* 'data' => 'Top',
26+
* 'locale' => 'en_US',
27+
* 'scope' => null
28+
* ],
29+
* [
30+
* 'data' => 'Débardeur',
31+
* 'locale' => 'fr_FR',
32+
* 'scope' => null
33+
* ],
34+
* ],
35+
* ],
36+
* 'created' => '2022-08-23T18:24:44+02:00',
37+
* 'updated' => '2022-08-25T17:56:12+02:00',
38+
* 'associations' => [
39+
* 'PACK' => [
40+
* 'products' => [
41+
* '12951d98-210e-4bRC-ab18-7fdgf1bd14f5'
42+
* ],
43+
* 'groups' => [],
44+
* 'product_models' => []
45+
* ],
46+
* ],
47+
* 'quantified_associations' => [
48+
* 'PRODUCT_SET' => [
49+
* 'products' => [
50+
* ['uuid' => '12951d98-210e-4bRC-ab18-7fdgf1bd14f4', 'quantity' => 2],
51+
* ],
52+
* 'product_models' => [],
53+
* ],
54+
* ],
55+
* ]
56+
*/
57+
$product = $client->getProductUuidApi()->get('12951d98-210e-4bRC-ab18-7fdgf1bd14f3');
58+
```
59+
60+
#### Get a list of products
61+
::: php-client-availability versions=10.0 editions=CE,EE
62+
63+
There are two ways of getting products. Also, you have a search builder to ease the construction of a research.
64+
65+
**Search builder**
66+
67+
You can search over the products, thanks to a list of filters.
68+
An helper has been added to ease the construction of these filters.
69+
70+
For more information about the available filters and operators that you can use to research a list of products, please refer to [this page](/documentation/filter.html).
71+
72+
```php
73+
$searchBuilder = new \Akeneo\Pim\ApiClient\Search\SearchBuilder();
74+
$searchBuilder
75+
->addFilter('enabled', '=', true)
76+
->addFilter('completeness', '>', 70, ['scope' => 'ecommerce'])
77+
->addFilter('completeness', '<', 85, ['scope' => 'ecommerce'])
78+
->addFilter('categories', 'IN', 'winter_collection')
79+
->addFilter('family', 'IN', ['camcorders', 'digital_cameras']);
80+
81+
$searchFilters = $searchBuilder->getFilters();
82+
```
83+
84+
**By getting pages**
85+
86+
This method allows to get products page per page, as a classical pagination. You can research products thanks to the search builder.
87+
88+
As for the other entities, it's possible to get the total number of researched products with this method.
89+
Also, it's possible to filter the value to return, thanks to the query parameters that are fully described [here](/api-reference.html#get_products).
90+
91+
For example, in this example, we only return product values belonging to the channel "ecommerce" by adding the query parameter `'scope' => 'ecommerce'`.
92+
93+
```php
94+
$client = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
95+
96+
$searchBuilder = new \Akeneo\Pim\ApiClient\Search\SearchBuilder();
97+
$searchBuilder
98+
->addFilter('completeness', '>', 70, ['scope' => 'ecommerce'])
99+
->addFilter('completeness', '<', 85, ['scope' => 'ecommerce']);
100+
$searchFilters = $searchBuilder->getFilters();
101+
102+
// set the limit of 50 products per page, calculate the total number of researched products, apply a research
103+
$firstPage = $client->getProductUuidApi()->listPerPage(50, true, ['search' => $searchFilters, 'scope' => 'ecommerce']);
104+
```
105+
106+
::: warning
107+
There is a maximum limit allowed on server side for the parameter `limit`.
108+
:::
109+
110+
::: warning
111+
Setting the parameter `with_count` to `true` can drastically decrease the performance.
112+
It's recommended to let this parameter with the default value `false` if the total number of products is not needed in the response.
113+
:::
114+
115+
You can get more information about this method [here](/php-client/list-resources.html#by-getting-pages).
116+
117+
You can get more information about the available query parameters [here](/api-reference.html#get_products).
118+
119+
**With a cursor**
120+
121+
This method allows to iterate the products. It will automatically get the next pages for you.
122+
With this method, it's not possible to get the previous page, or getting the total number of products.
123+
124+
As for the paginated method, the search builder can be used and all query parameters are available, except `with_count`.
125+
126+
For example, in this example, we only return product values belonging to the channel "ecommerce" by adding the query parameter `'scope' => 'ecommerce'`.
127+
128+
```php
129+
$client = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
130+
131+
$searchBuilder = new \Akeneo\Pim\ApiClient\Search\SearchBuilder();
132+
$searchBuilder
133+
->addFilter('completeness', '>', 70, ['scope' => 'ecommerce'])
134+
->addFilter('completeness', '<', 85, ['scope' => 'ecommerce']);
135+
$searchFilters = $searchBuilder->getFilters();
136+
137+
// get a cursor with a page size of 50, apply a research
138+
$products = $client->getProductUuidApi()->all(50, ['search' => $searchFilters, 'scope' => 'ecommerce']);
139+
```
140+
:::warning
141+
There is a maximum limit allowed on server side for the parameter `pageSize`.
142+
:::
143+
144+
You can get more information about this method [here](/php-client/list-resources.html#with-a-cursor).
145+
146+
You can get more information about the available query parameters [here](/api-reference.html#get_products).
147+
148+
#### Create a product
149+
::: php-client-availability versions=9.0 editions=CE,EE
150+
151+
If the product does not exist yet, this method creates it, otherwise it throws an exception.
152+
153+
```php
154+
$client = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
155+
156+
$client->getProductUuidApi()->create('844c736b-a19b-48a6-a354-6056044729f0', [
157+
'identifier' => 'top',
158+
'enabled' => true,
159+
'family' => 'tshirt',
160+
'categories' => ['summer_collection'],
161+
'groups' => [],
162+
'parent'=> null,
163+
'values' => [
164+
'name' => [
165+
[
166+
'data' => 'top',
167+
'locale' => 'en_US',
168+
'scope' => null,
169+
],
170+
[
171+
'data' => 'Débardeur',
172+
'locale' => 'fr_FR',
173+
'scope' => null,
174+
],
175+
],
176+
'price' => [
177+
[
178+
'data' => [
179+
[
180+
'amount' => '15.5',
181+
'currency' => 'EUR',
182+
],
183+
[
184+
'amount' => '15',
185+
'currency' => 'USD',
186+
],
187+
],
188+
'locale' => null,
189+
'scope' => null,
190+
],
191+
],
192+
]
193+
);
194+
```
195+
196+
You can get more information about the expected format of the product values [here](/concepts/products.html#focus-on-the-product-values).
197+
198+
#### Upsert a product
199+
::: php-client-availability versions=9.0 editions=CE,EE
200+
201+
If the product does not exist yet, this method creates it, otherwise it updates it.
202+
203+
```php
204+
$client = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
205+
206+
$client->getProductUuidApi()->upsert('844c736b-a19b-48a6-a354-6056044729f0', [
207+
'identifier' => 'top',
208+
'enabled' => true,
209+
'family' => 'tshirt',
210+
'categories' => ['summer_collection'],
211+
'groups' => [],
212+
'parent'=> null,
213+
'values' => [
214+
'name' => [
215+
[
216+
'data' => 'top',
217+
'locale' => 'en_US',
218+
'scope' => null,
219+
],
220+
[
221+
'data' => 'Débardeur',
222+
'locale' => 'fr_FR',
223+
'scope' => null,
224+
],
225+
],
226+
'price' => [
227+
[
228+
'data' => [
229+
[
230+
'amount' => '15.5',
231+
'currency' => 'EUR',
232+
],
233+
[
234+
'amount' => '15',
235+
'currency' => 'USD',
236+
],
237+
],
238+
'locale' => null,
239+
'scope' => null,
240+
],
241+
],
242+
]
243+
);
244+
```
245+
246+
You can get more information about the expected format of the product values [here](/concepts/products.html#focus-on-the-product-values).
247+
248+
#### Upsert a list of products
249+
::: php-client-availability versions=9.0 editions=CE,EE
250+
251+
This method allows to create or update a list of products.
252+
It has the same behavior as the `upsert` method for a single product, except that the code must be specified in the data of each product.
253+
254+
255+
```php
256+
$client = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
257+
258+
$responseLines = $client->getProductUuidApi()->upsertList([
259+
[
260+
'uuid' => '12951d98-210e-4bRC-ab18-7fdgf1bd14f3',
261+
'identifier' => 'top',
262+
'family' => 'tshirt',
263+
'categories' => ['summer_collection'],
264+
'groups' => [],
265+
'values' => [
266+
'price' => [
267+
[
268+
'data' => [
269+
[
270+
'amount' => '15.5',
271+
'currency' => 'EUR',
272+
],
273+
[
274+
'amount' => '15',
275+
'currency' => 'USD',
276+
],
277+
],
278+
'locale' => null,
279+
'scope' => null,
280+
],
281+
],
282+
],
283+
],
284+
[
285+
'uuid' => '12951d98-210e-4bRC-ab18-7fdgf1bd14f4',
286+
'identifier' => 'cap',
287+
'categories' => ['hat'],
288+
],
289+
]);
290+
291+
foreach ($responseLines as $line) {
292+
echo $line['line'];
293+
echo $line['identifier'];
294+
echo $line['status_code'];
295+
if (isset($line['message'])) {
296+
echo $line['message'];
297+
}
298+
}
299+
```
300+
301+
::: warning
302+
There is a limit on the maximum number of products that you can upsert in one time on server side. By default this limit is set to 100.
303+
:::
304+
305+
You can get a complete description of the expected format and the returned format [here](/api-reference.html#get_products__code_).
306+
307+
#### Delete a product
308+
::: php-client-availability versions=1.0,2.0,3.0,4.0,5.0,6.0 editions=CE,EE
309+
310+
```php
311+
$client = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
312+
313+
$client->getProductUuidApi()->delete('12951d98-210e-4bRC-ab18-7fdgf1bd14f4');
314+
```

‎tasks/build-doc.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -672,7 +672,7 @@ gulp.task('create-app-catalog-md', function () {
672672
});
673673

674674
gulp.task('create-products-md', function () {
675-
return gulp.src(['content/php-client/resources/products/products.md','content/php-client/resources/products/product-models.md','content/php-client/resources/products/*.md'])
675+
return gulp.src(['content/php-client/resources/products/products.md','content/php-client/resources/products/products-uuid.md','content/php-client/resources/products/product-models.md','content/php-client/resources/products/*.md'])
676676
.pipe(concat('products.md'))
677677
.pipe(insert.prepend('## Products\n'))
678678
.pipe(gulp.dest('tmp/php-client-resources/'));

0 commit comments

Comments
 (0)