Lesson 8. How to make changes via the API
In this lesson, you will learn:
All the data-changing methods, such as add, update, delete, accept an array of objects as an input. Each object contained in the request is processed separately. For example, if your app has sent a request to create 100 ads and an error has occurred to 10 of them, the other 90 ads are created successfully. The API server returns IDs for the 90 ads created, and errors for the other 10 ads.
If errors preclude request execution (for example, their format is invalid or a required parameter is missing), the request is rejected completely.
Your app must take this into account while interacting with the API to properly handle errors returned by the server.
How to edit object parameters
When using the update method to change an object, you do not have to pass all the object parameters. You only have to specify the object ID and the parameters to be changed. The other parameters won't be changed. The Yandex Direct server will still check the entire object and return an error if the object has become invalid with the new parameter values.
Sandbox practice
In the previous lesson, we got a list of all campaigns. Now let's continue working with one of the campaigns: enable separate bid management on search and in ad networks.
- cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"update","params":{"Campaigns":[{"Id":CAMPAIGN_ID,"TextCampaign":{"BiddingStrategy":{"Network":{"BiddingStrategyType":"MAXIMUM_COVERAGE"}}}}]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns
- cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"update\",\"params\":{\"Campaigns\":[{\"Id\":CAMPAIGN_ID,\"TextCampaign\":{\"BiddingStrategy\":{\"Network\":{\"BiddingStrategyType\":\"MAXIMUM_COVERAGE\"}}}}]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns
- Request
{ "method": "update", "params": { "Campaigns": [{ "Id": CAMPAIGN_ID, "TextCampaign": { "BiddingStrategy": { "Network": { "BiddingStrategyType": "MAXIMUM_COVERAGE" } } } }] } }
- Response
{ "result": { "UpdateResults": [{ "Id": CAMPAIGN_ID }] } }
Task
- AdGroups service
-
Add an ad group.
cURLcurl -k -H "Authorization: Bearer TOKEN" -d '{"method":"add","params":{"AdGroups":[{"Name":"New ad group","CampaignId":CAMPAIGN_ID,"RegionIds":[213]}]}}' https://api-sandbox.direct.yandex.com/json/v5/adgroups
cURL for Windowscurl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"add\",\"params\":{\"AdGroups\":[{\"Name\":\"New ad group\",\"CampaignId\":CAMPAIGN_ID,\"RegionIds\":[213]}]}}" https://api-sandbox.direct.yandex.com/json/v5/adgroups
Request{ "method": "add", "params": { "AdGroups": [{ "Name": "New group", "CampaignId": CAMPAIGN_ID, "RegionIds": [213] }] } }
Response{ "result": { "AddResults": [{ "Id": GROUP_ID }] } }
- Ads service
-
Create ads in an ad group.
cURLcurl -k -H "Authorization: Bearer TOKEN" -d '{"method":"add","params":{"Ads":[{"AdGroupId":AD_GROUP_ID,"TextAd":{"Title":"Ad title","Text":"Ad text","Mobile":"NO","Href":"http://example.com"}}]}}' https://api-sandbox.direct.yandex.com/json/v5/ads
cURL for Windowscurl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"add\",\"params\":{\"Ads\":[{\"AdGroupId\":AD_GROUP_ID,\"TextAd\":{\"Title\":\"Ad title\",\"Text\":\"Ad text\",\"Mobile\":\"NO\",\"Href\":\"http://example.com\"}}]}}" https://api-sandbox.direct.yandex.com/json/v5/ads
Request{ "method": "add", "params": { "Ads": [{ "AdGroupId": "GROUP_ID", "TextAd": { "Title": "Ad title", "Text": "Ad text", "Mobile": "NO", "Href": "http://example.com" } }] } }
Response{ "result": { "AddResults": [{ "Id": AD_ID }] } }
- Keywords service
Add a keyword.
cURLcurl -k -H "Authorization: Bearer TOKEN" -d '{"method":"add","params":{"Keywords":[{"Keyword":"New keyword","AdGroupId":AD_GROUP_ID,"Bid":300000}]}}' https://api-sandbox.direct.yandex.com/json/v5/keywords
cURL for Windowscurl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"add\",\"params\":{\"Keywords\":[{\"Keyword\":\"New keyword\",\"AdGroupId\":AD_GROUP_ID,\"Bid\":300000}]}}" https://api-sandbox.direct.yandex.com/json/v5/keywords
Request{ "method": "add", "params": { "Keywords": [{ "Keyword": "New keyword", "AdGroupId": GROUP_ID, "Bid": 300000 }] } }
Response{ "result": { "AddResults": [{ "Id": YOUR_KEYWORD_ID }] } }
- KeywordBids service
-
Change bid for a single keyword.
cURLcurl -k -H "Authorization: Bearer TOKEN" -d '{"method":"set","params":{"KeywordBids":[{"KeywordId":KEYWORD_ID,"SearchBid":400000}]}}' https://api-sandbox.direct.yandex.com/json/v5/keywordbids
cURL for Windowscurl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"set\",\"params\":{\"KeywordBids\":[{\"KeywordId\":KEYWORD_ID,\"SearchBid\":400000}]}}" https://api-sandbox.direct.yandex.com/json/v5/keywordbids
Request{ "method": "set", "params": { "KeywordBids": [{ "KeywordId": YOUR_KEYWORD_ID, "SearchBid": 400000 }] } }
Response{ "result": { "SetResults": [{ "KeywordId": YOUR_KEYWORD_ID }] } }
What's next
So you have learned how to make requests in Sandbox, both to get and change data. Now it's time to graduate from Sandbox practice to real life experience.
Useful links
Documentation: How methods that change data work
Questions
- What happens, if a request to create five ads contains an error in one ad?False.True.False.False.
- What set of parameters has to be passed in update requests?False.True.False.
- What method of the Campaigns service is used to create campaigns?False.False.True.