Lesson 8. How to make changes via the API

In this lesson, you will learn:

  1. How to edit object parameters
  2. Sandbox practice
  3. Task
  4. What's next
  5. Useful links
  6. Questions

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.

Attention. The object ID is returned only if the operation has been completed successfully (warnings may also be issued).


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

We have prepared some samples for other services as well. Try to reproduce these requests in Sandbox.
AdGroups service

Add an ad group.

cURL
curl -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 Windows
curl -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 ad group",
      "CampaignId": CAMPAIGN_ID,
      "RegionIds": [213]
    }]
  }
}
Response
{
  "result": {
    "AddResults": [{
      "Id": AD_GROUP_ID
    }]
  }
}
Ads service

Create ads in an ad group.

cURL
curl -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 Windows
curl -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": "AD_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.

cURL
curl -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 Windows
curl -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": AD_GROUP_ID,
      "Bid": 300000
    }]
  }
}
Response
{
  "result": {
    "AddResults": [{
      "Id": KEYWORD_ID
    }]
  }
}
KeywordBids service

Change bid for a single keyword.

cURL
curl -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 Windows
curl -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": KEYWORD_ID,
      "SearchBid": 400000
    }]
  }
}
Response
{
  "result": {
    "SetResults": [{
      "KeywordId": 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.

Questions

  1. What happens, if a request to create five ads contains an error in one ad?
    False.
    True.
    False.
    False.
  2. What set of parameters has to be passed in update requests?
    False.
    True.
    False.
  3. What method of the Campaigns service is used to create campaigns?
    False.
    False.
    True.