Magento Content API Technical Overview

Transcription

1 Magento Content API Technical Overview Overview GoogleShopping module provides the API that enables to communicate with Google Merchant Center to upload and edit product data; it replaces depreciated in June 2011 Google Base API. Google Shopping API consists of two parts: Content and Search; Content API allows insert, update, delete and retrieve product's info; Search API allows search by uploaded items which is not part of this implementation. Mage_GoogleShopping v0.3 implements only Content API functionality. Zend Framework Gdata that is used by Base API module hadn't been updated when development started, so there was a new Varien_Gdata_Gshopping library added; structure Mage_GoogleShopping module is similar to structure Mage_GoogleBase module, re-factored in version 0.3. This document describes version 0.3 of module. Google's API description can be found in Varien_Gdata_Gshopping library The library extends functionality of Zend_Gdata library; it's architecture and functionality is like Zend_Gdata_Gbase module. Main functionality of the module is concentrated in two classes: Varien_Gdata_Gshopping_Content and Varien_Gdata_Gshopping_Entry. Varien_Gdata_Gshopping_Content This class is responsible for inserting, updating, deletion and retrieving entries; method performhttprequest() wraps Zend_Gdata_App_HttpException with Varien_Gdata_Gshopping_HttpException to parse error response from Google. Varien_Gdata_Gshopping_Entry This class extends functionality of Zend_Gdata_Entry with functions for processing (parsing from DOM and generation DOM) content attributes (<sp:attribute>) and some special attributes as taxes and destinations. The module uses several children of Zend_Gdata_App_Extension_Element for parsing and building sub-elements of entry it's: Varien_Gdata_Gshopping_Extension_Attribute is used for processing <sc:attribtue> of an entry; Varien_Gdata_Gshopping_Extension_Control is used to work with destinations; Varien_Gdata_Gshopping_Extension_Shipping was designed to work with shipping information, but isn't used by Mage_GoogleShopping module because we're unable to send any appropriate shipping information when we don't know shipping destination; Varien_Gdata_Gshopping_Extension_Tax is used for processing tax information for united states. Varien_Gdata_Gshopping_HttpException This class extends Zend_Gdata_App_HttpException and tries to parse error info from response's body. It overrides constructor to add capability to build class from Zend_Gdata_App_HttpException instance and adds some getters for error info extracted from response body. Mage_GoogleShopping module This module adds functionality for manipulation of entries to admin panel. During installation it creates three tables: googleshopping_attributes, googleshopping_items and googleshopping_types; adds menu Catalog Google Content (with related pages) and page with configuration options to Sales Google API section. Database schema

2 As written above the module creates such tables: googleshopping_attributes contains map from products' attributes to Google's attributes; googleshopping_items contains information about attributes uploaded to Google; googleshopping_types contains map from types (set of mapped attributes) to attributes' sets. Blocks The blocks has structure similar to Mage_GoogleBase blocks; all blocks are children of Mage_Adminhtml_Block classes and used for creating interface in admin panel. Also there are four templates in app/design/adminhtml/default/default/template/googleshopping folder. Controllers The module has three controllers: Mage_GoogleShopping_Adminhtml_Googleshopping_ItemsController serves grid of items; Mage_GoogleShopping_Adminhtml_Googleshopping_SelectionController handles product selection's grid on items page; Mage_GoogleShopping_Adminhtml_Googleshopping_TypesController serves types page. Models Item Mage_GoogleShopping_Model_Item class is a Google Content's item and it responsible for insert, update and delete item. All these items are stored in the Magento's database ( googleshopping_items table) and contains only main information about item. So, this model has resource model ( Mage_GoogleShopping_Model_Mysq4_Item), which is responsible for saving and loading item's data from the database. Also this model has service model ( Mage_GoogleShopping_Model_Service_Item), which is responsible for storing and receiving items from Google Content service.

3 Mage_GoogleShopping_Model_Item This class works with Mage_GoogleShopping_Model_Service_Item class for working with Google's items Main methods: insertitem - add (send) product to Google Content updateitem - updatete current item's data in Google Content deleteitem - delete item from Google Content load - load item from Magento's database save - save item's model to database delete - delete items from database gettype - get type of item (about types - see below) getproduct - get/load product model (catalog/product) which is associated with item Mage_GoogleShopping_Model_Service_Item This class works with Varien_Gdata library for working with Google's items Main methods: insert - add item to Google Content update - update item's data in Google Content delete - delete item from Google Content

4 // load product before $product = Mage::getModel('catalog/product') ->setstoreid($storeid) ->load($productid); // create item and save it in the DB Mage::getModel('googleshopping/item') ->insertitem($product) ->save(); Insert, update and delete product to Google Content // update item (if something in the product was changed) Mage::getModel('googleshopping/item') ->loadbyproduct($product) ->updateitem() ->save(); //delete item Mage::getModel('googleshopping/item') ->loadbyproduct($product) ->deleteitem() ->delete(); Attribute's type. Each item has a type, which describes how this item should save to Google Content, i.e. how product's attributes should be provided. In user interface, types are named as "mapping". The types data is storing in table googleshopping_types, and type's attributes in the table googleshopping_attributes. Each type is characterized by the target country and attribute set, so we can set different representations for different products from different stores (each store can have own target country) in Google Content base. So, class Mage_GoogleShopping_Model_Type responsibles for saving and loading types from Magento's database (using resource model Mage_GoogleShopping_Model_Mysql4_Type), and also for set attributes to entry ( Varien_Gdata_Gshopping_Entry) from product's model (using mapping data). In order to update product's attribute to entry, we should use method convertproducttoentry. Mage_GoogleShopping_Model_Type Attributes convertproducttoentry - main method of this class, find all attributes for current product and add/update/delete them in the entry object. loadbyattributesetid - load type for some attribute set and target country Each attribute, which will be sent to Google, is represented by class Mage_GoogleShopping_Model_Attribute. The attributes can be exported in Google Content by different ways, and the models Mage_GoogleShopping_Model_Attribute_<name> (where <name> is Google attribute's name) responsible for how they will be exported to Google. So, when we call method Mage_GoogleShopping_Model_Type->convertProductToEntry, it calls method convertattribute for all attribute models. If some attribute hasn't model (class Mage_GoogleShopping_Model_Attribute_<name> hasn't been found), it will use model Mage_GoogleShopping_Model_Attribute_Default. The list of all attributes, which should be sent to Google, consists of: base attributes (requires attributes which must be sent to Google) and attributes from mapping (attributes which user was added to type in the Catalog -> Google Content -> Manage Attributes). The list of base attributes is listed in config.xml (the tag base_attributes). It is such attributes as id, title, price, target_country, etc.

5 Mage_GoogleShopping_Model_Attribute_Default Default attribute model. All other attribute models should extend this class. convertattribute - method which add, update or delete attribute to entry object ( Varien_Gdata_Gshopping_Entry). Grouped attributes Some attributes may have strong dependence between each other. For instance, attribute tax depends on attribute price, because tax depends on how price is setting/calculating (include or exclude tax), it affects how tax will be send to Google Content. Also Google Content has synonyms for some attribute names (one attribute can have two names). For instance, product's name can be sent as name attribute or as title attribute, but it is impossible send name and title attributes together, in one entry. In order to solve such problems, the attribute model has a possibility to take access to another attribute. So, price attribute has access to tax attribute and it can use method $this->getgroupattributetax() for get tax attribute's model. Also price attribute responsible for how to add tax attribute to entry object (using method convertattribute}), price model can add or don't add tax attribute. The group attribute dependencies are set in config.xml (tag attribute_groups). Mage_GoogleShopping_Model_MassOperations This model responsible for mass actions with Google Content items. It is used by controller ( Mage_GoogleShopping_Adminhtml_Googleshopping_ItemsController) and observer ( Mage_GoogleShopping_Model_Observer). It contains next operations: addproducts - add several products to Google Content by their IDs. synchronizeitems - update items, synchronize their attributes data. deleteitems - delete items from Google Content and Magento's database.

6 Insert, update and delete several products to Google Content // add to Google Content products with IDs = 5, 6 and 7 for store with ID = 2 Mage::getModel('googleshopping/massOperations') ->addproducts(array(5, 6, 7), 2); // update products in the Google Content $items = Mage::getResourceModel('googleshoping/items_collection') ->addfieldtofilter('product_id', array(5, 6, 7)) ->addstorefilter(2); Mage::getModel('googleshopping/massOperations') ->synchronizeitems($items); // delete products in the Google Content $items = Mage::getResourceModel('googleshoping/items_collection') ->addfieldtofilter('product_id', array(5, 6, 7)) ->addstorefilter(2); Mage::getModel('googleshopping/massOperations') ->deleteitems($items); Mage_GoogleShopping_Model_Observer The observer updates Google after updating and deletion product. Source models The module uses several source models: Mage_GoogleShopping_Model_Source_Accounttype; Mage_GoogleShopping_Model_Source_Authtype; Mage_GoogleShopping_Model_Source_Country; Mage_GoogleShopping_Model_Source_Destinationstates; Mage_GoogleShopping_Model_Source_Statuses. Resource models Due to model uses database there are several resource models: Mage_GoogleShopping_Model_Mysql4_Type; Mage_GoogleShopping_Model_Mysql4_Type_Collection; Mage_GoogleShopping_Model_Mysql4_Item; Mage_GoogleShopping_Model_Mysql4_Item_Collection; Mage_GoogleShopping_Model_Mysql4_Attribute; Mage_GoogleShopping_Model_Mysql4_Attribute_Collection. Helpers The module uses two helpers: Mage_GoogleShopping_Helper_Data and Mage_GoogleShopping_Helper_Price. Data helper it's generic helper and it's used in templates. Price helper it's workaround for problem of getting price as it displayed in catalog; abstract price model doesn't have interface to get minimal price of grouped, bundle, gift card products, but on frontend customer can see this price.