This CDK package shows an example of utilizing Buy with Prime's events and API. This package is based on the Mock API and Mock events, not the Buy with Prime production API, or production events. If you do not have a Buy with Prime Accelerator to generate Mock APIs and Mock Events, please request one from your Buy with Prime SA. If you don't have point of contact, please reach out to BwP-feedback@amazon.com.
This sample demonstrates an example of event hydration for:
- order event :
ORDER_PLACED
,ORDER_UPDATED
,REFUND_SUCCESS
. - buyability and inventory event
The order event stack extracts an orderId
from a mock order event. Using that ID, the stack calls the Buy with Prime Mock API to query information about a single order. You can see the Buy with Prime query example in singleOrder.graphql
and it's sample query response. This sample code stores the response in a format of text file. You can see the actual example from sample object.
- Inventory event: Work in Progress.
The event hydrator checks if the event has
identifierType
as anitemId
. If so, it extractsidentifierValue
, which is a uniqueitemId
. Using that ID, the Lambda function sends the item query to the Buy with Prime Mock API. You can see the item query initemByID.graphql
and it's sample query response.
- Deploy Buy with Prime accelerator in your AWS account.
- Prepare your S3 bucket to store Buy with Prime data.
- AWS Secrets Manager
- Amazon EventBridge
- Amazon SQS and Dead Letter Queue
- AWS Lambda
- Amazon S3
The lambda function hydrates Buy with Prime events, parsing orderId
, sends order
query as written in singleOrder.graphql
. You can edit the file by eliminating unnecessary fields, or replace with other GraphQL queries/mutations. If you want to know each field of order query, or other APIs, please find Buy with Prime API reference.
- Extract
order_id
from the event payload - Call
order
with theorder_id
to get all information of a single order. - Store the response in S3 in the format of timestamp.
- Clone this repository.
- Update
.env
CLIENT_ID
andCLIENT_SECRET
: When you have your client ID after onboarding process completed. (Optional)S3_BUCKET_ARN
EVENT_BUS_ARN
- your Buy with Prime Accelerator's EventBridge ARN.MOCK_BWP_API
- your Buy with Prime Accelerator's Appsync endpoint.AWS_REGION
- Your AWS region.
- Run cdk commands.
cdk bootstrap
cdk deploy
You can generate a mock Buy with Prime event by calling Buy with Prime accelerator's event API. The mock event API endpoint can be found in the Amazon API Gateway under the name Event-api
.
ORDER_PLACED
,ORDER_UPDATED
,REFUND_SUCCESS
.
curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/order?event-type=order_placed'
curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/order?event-type=order_updated'
curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/order?event-type=refund_success'
curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/buyability?event-type=buyability'
curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/inventory?event-type=inventory'
This event accelerator has two custom rules to forward events to different targets based on the event types.
The CDK has sample event pattern to filter Buy with Prime event types. You can update the rules in lib/cdk-stack.ts
.
eventPattern: {
"detail": {
"eventType": ["ORDER_PLACED", "ORDER_UPDATED", "REFUND_SUCCESS"]
}
},
eventPattern: {
"detailType": ["santos.buyability.status.change", "INVENTORY_AVAILABILITY_CHANGED"]
},
The lambda function looks at the value of detail-type
in the event payload to determine the event type. If the value is INVENTORY_AVAILABILITY_CHANGED
, it extracts inventoryItemId
from the event payload, and queries inventory with it. Or, if the value is santos.buyability.status.change
, it extracts itemId
instead, and queries buyability.
The inventory query provides the buyable quantity, as well as the external ID and SKU of the mapping product. The following is an example of an inventory query response.
{
"data": {
"inventoryItem": {
"buyableQuantity": {
"amount": 10,
"unit": "DAYS"
},
"inventoryItemId": "w6ibvyca8tmh83",
"mappingProduct": {
"externalId": "93c711ed-517d-4e45-873f-b615dc97dd6a",
"id": "w6ibvyca8tmh83",
"isPrimeIntended": true,
"sku": "8f72b379-b669-46a5-a37d-7b2e07b227a4",
"url": "https://testurl"
}
}
}
}
The buyability query, on the other hand, takes a variety of arguments, including ID, external ID, SKU, and mSKU, and returns a buyable status. This sample shows an example of using an ID. The following is an example of a buyability query response.
{
"data": {
"buyability": {
"status": "true"
}
}
}
Unlike REST, GraphQL will return a response with code 200
, regardless of whether or not there was an error in the call. A 200
in GraphQL simply means that the endpoint is available and you successfully made a call. Instead of using specific error codes, GraphQL reports errors by adding error blocks. This allows for much more granual error reporting than generic response codes. For more on Errors in GraphQL, see the GraphQL spec documentation here.
This Event accelerator is designed to handle GraphQL errors in these scenarios:
- The response status is not 200. This means the endpoint is not available
- The response body contains an "errors" section. This means the call was sent successfully, but there was an error during execution
...
if response.status != 200 or 'errors' in str(response_data): // detect errors
print("response", response.status, response_text)
else:
...
This is an example response to an Order query when the Order object doesn't exist. The HTTP response status would still be 200. However, the body of the response contains details of the errors. You should consider these cases when building out your GraphQL error handling.
response 200
{
"data": {
"order": null
},
"errors": [
{
"path": [
"order"
],
"data": null,
"errorType": "MappingTemplate",
"errorInfo": null,
"locations": [
{
"line": 2,
"column": 3,
"sourceName": null
}
],
"message": "Template transformation yielded an empty response."
}
]
}
Of course, you should also consider errors where the code is not 200. Find more information about errors by code in Buy with prime GraphQL API error codes.
- This sample code is designed based on Buy with Prime Accelerator, not using neither production events or APIs.
- Buy with Prime Accelerator uses static token, so this sample does not contain authentication logic to store or refresh tokens.
By running cdk command, you can clear most of the resources.
cdk destroy
However, you need to manually delete these resources.
- Amazon S3 bucket: If the bucket is not empty,
cdk destroy
cannot delete the bucket. You need to empty the bucket before runningcdk destory
, or manually delete the bucket. - AWS Lambda Log groups: The CDK stack sets the log retention period to one month. If you want to delete a log group before this period, you can delete the log group manually. Go to Amazon CloudWatch > Logs > Log groups and filter for
EventAcceleratorStack
to find the log group.