All the steps discussed below focus on a simple task: searching for a set of origin behaviors in the configuration's top-level rule, and changing the origin server's hostname from old.example.com to new.example.com.
If you intend to use search results for a bulk update, make sure nobody else is modifying any of the property configurations before launching your search.
This simplified object shows the type of rule you want to match, available from the Get a rule tree operation's response:
{
"accountId": "act_1-1TJZFB",
"contractId": "ctr_1-1TJZH5",
"groupId": "grp_15225",
"propertyId": "prp_173136",
"propertyVersion": 3,
"etag": "a9dfe78cf93090516bde891d009eaf57",
"ruleFormat": "v2018-02-27",
"rules": {
"name": "default",
"criteria": [],
"behaviors": [
{
"name": "origin",
"options": {
"httpPort": 80,
"enableTrueClientIp": false,
"compress": true,
"cacheKeyHostname": "ORIGIN_HOSTNAME",
"forwardHostHeader": "REQUEST_HOST_HEADER",
"hostname": "old.example.com",
"originType": "CUSTOMER"
}
},
{
"name": "cpCode",
"options": {
"value": {
"id": 12345,
"name": "my CP code"
}
}
}
],
"children": []
}
}
Prepare a search
To match the specific hostname value within the origin behavior, you need a JSONPath expression as in this example:
$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname
The Sample bulk updates section lists other types of search, and the Contextual searches section provides more detailed guidance on the syntax. This expression applies two filters to a set of behaviors on the default rule. The first tests its name, and the second tests the value of its hostname option.
Specify the JSONPath expression as a match in a bulk search POST request object, for example:
{
"bulkSearchQuery": {
"syntax": "JSONPATH",
"match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname"
}
}
The bulkSearchQuery area collects all the details about your search. The only available syntax is JSONPATH. Make sure any double-quote characters in the match JSONPath value are escaped with backslashes, otherwise you can use single quotes, as in this example.
Qualify a search
Specifying additional search criteria can help you narrow down the scope of the search to a smaller set of property configurations.
Suppose you want all origins where the hostname is old.example.com, but only those tracked under a specific CP code. The information you want to test appears within the default rule as the cpCode behavior. Form another JSONPath expression with logic as in this example, which matches rule trees with a specific CP code value:
$.behaviors[?(@.name == 'cpCode'].options.value[?(@.id == 12345)].id
Specify this as bulkSearchQualifiers criteria. For the search to produce results, the match criteria needs to yield results, but only those where the full set of bulkSearchQualifiers also matches the configuration:
{
"bulkSearchQuery": {
"syntax": "JSONPATH",
"match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname",
"bulkSearchQualifiers": [
"$.behaviors[?(@.name == 'cpCode'].options.value[?(@.id == 12345)].id"
]
}
}
These additional qualifiers test the configuration independently from the match, and the locations they match within the rules don't appear as search results themselves.
There may be cases where a single
matchmay be able to combine all the logic you want within a single expression. But in some cases, specifying a separate set ofbulkSearchQualifiersmay allow you to simplify the mainmatchsyntax.
Launch a search
To launch the search, POST the bulk search object to this URL:
POST /papi/v1/bulk/rules-search-requests
Add optional contractId or groupId parameters if you want to narrow down the set of results:
POST /papi/v1/bulk/rules-search-requests?contractId=1-1TJZFW&groupId=15166
The response's Location header, or the response JSON's bulkSearchLink member, both provide a navigable link to call the next operation. Store this URL path value before proceeding to the next step:
{
"bulkSearchLink": "/papi/v1/bulk/rules-search-requests/737"
}
For full details on the POST operation, see Bulk search a set of properties.
If you provision an ordinary Akamai API token, search results apply to a single account. Review Get started for a way to provision your API token to search properties across all your accounts.
Check search results
After launching the bulk search, make a GET call on the link provided in the POST response. For example:
GET /papi/v1/bulk/rules-search-requests/737
For details on this GET operation, see List bulk search results.
The response object reflects back the original request's bulkSearchQuery, to provide you context to help interpret the additional search results, which span all properties available to you in any account:
{
"bulkSearchId": 5,
"searchTargetStatus": "IN_PROGRESS",
"searchSubmitDate": "2018-01-18T00:00:00Z",
"searchUpdateDate": "2018-01-18T00:01:00Z",
"bulkSearchQuery": {
"syntax": "JSONPATH",
"match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname"
},
"results": [
{
"propertyId": "prp_15",
"propertyVersion": 2,
"stagingStatus": "INACTIVE",
"productionStatus": "ACTIVE",
"lastModifiedTime": "2018-01-18T00:00:00Z",
"matchLocations": [
"/rules/behaviors/0/options/hostname"
]
}
]
}
Check the searchTargetStatus value:
-
If it's either
PENDINGorIN_PROGRESS, the searchresultsaren't yet finalized. Wait some time, then run the GET operation again to poll the result. -
Once it's
COMPLETE, search results are ready. The amount of time it takes to get a set ofCOMPLETEresults depends on the number of properties you're searching, the size of the configuration, and the complexity of thematchexpression.
The results include up to three versions for each propertyId:
-
active on the staging network
-
active on the production network
-
most recently modified version
This simplified example features only two search results:
{
"bulkSearchId": 5,
"searchTargetStatus": "COMPLETE",
"searchSubmitDate": "2018-01-18T00:00:00Z",
"searchUpdateDate": "2018-01-18T00:01:00Z",
"bulkSearchQuery": {
"syntax": "JSONPATH",
"match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname"
},
"results": [
{
"propertyId": "prp_1",
"propertyVersion": 1,
"stagingStatus": "ACTIVE",
"productionStatus": "INACTIVE",
"lastModifiedTime": "2018-01-18T00:00:00Z",
"matchLocations": [
"/rules/behaviors/0/options/hostname"
]
},
{
"propertyId": "prp_15",
"propertyVersion": 2,
"stagingStatus": "INACTIVE",
"productionStatus": "ACTIVE",
"lastModifiedTime": "2018-01-18T00:00:00Z",
"matchLocations": [
"/rules/behaviors/0/options/hostname"
]
}
]
}
The matchLocations provides a set of JSON Pointer values, whose path expressions locate where within the rules the old.example.com value appears. This example shows a single match location. Other types of search may yield additional matches within the configuration.
The
matchLocationsincluded in the search results don't indicate the current value at each location. If you intend to use the search results to bulk-update your configurations, compare them to the originally specifiedmatchto confirm the scope of your initial search is what you intend.
You can use bulk search simply as a research tool, using the propertyId and propertyVersion values to modify individual configurations.
Assuming you want to update the configurations, save the results array, which you'll need to bulk patch them. If you want to update currently active versions, you first need to use the data to create a new set of editable property versions.
As an alternative to the two-step asynchronous bulk search operations, you can also run a single operation: Synchronously bulk search a set of properties. You POST the same initial request to a different
/papi/v1/bulk/rules-search-requests-synchURL endpoint. It yields the same response object as the GET, but with potentially long latency for the entire set of search results toCOMPLETE. It's more appropriate to run for small-batch bulk searches.