帮酷LOGO
  • 显示原文与译文双语对照的内容
文章标签:API  Json Api  
Create a JSON API for your elements in Craft.

  • 源代码名称:element-api
  • 源代码网址:http://www.github.com/craftcms/element-api
  • element-api源代码文档
  • element-api源代码下载
  • Git URL:
    git://www.github.com/craftcms/element-api.git
  • Git Clone代码到本地:
    git clone http://www.github.com/craftcms/element-api
  • Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/craftcms/element-api
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
  • 用于工艺CMS的元素 API

    这个插件使你可以轻松地为你的条目( 和其他元素类型) 在工艺CMS中创建一个 JSON API 。

    它是由Phil的sturgeon 分形封装强大的动力。

    要求

    这里插件需要工艺 CMS 3.0.0 -RC11或者更高版本。

    安装

    要安装插件,请按照以下说明操作。

    打开你的终端并进入你的工艺项目:

     cd/path/to/project

    然后告诉Composer加载插件:

     composer require craftcms/element-api

    在 控制面板 中,转到设置→插件,然后单击元素API的"安装"按钮。

    设置

    要定义API端点,在 craft/config/文件夹中创建一个新的element-api.php 文件。 这个文件应该返回一个带有 endpoints 键的array,它定义了你的站点端点的API 。 在 endpoints array 中,键是URL模式,值是端点配置。

    <?phpusecraftelementsEntry;usecrafthelpersUrlHelper;return ['endpoints'=> ['news.json'=> ['elementType'=>Entry::class,'criteria'=> ['section'=>'news'],'transformer'=>function(Entry$entry) {return ['title'=>$entry->title,'url'=>$entry->url,'jsonUrl'=>UrlHelper::url("news/{$entry->id}.json"),'summary'=>$entry->summary, ]; }, ],'news/<entryId:d+>.json'=>function($entryId) {return ['elementType'=>Entry::class,'criteria'=> ['id'=>$entryId],'one'=>true,'transformer'=>function(Entry$entry) {return ['title'=>$entry->title,'url'=>$entry->url,'summary'=>$entry->summary,'body'=>$entry->body, ]; }, ]; }, ]];

    端点配置设置

    端点配置数组可以包含以下设置:

    class

    应用于请求请求的分形资源的类 NAME 。 如果未设置这里选项,则默认为 craftelementapiresourcesElementResource ( 所有下列配置设置都特定于该默认类。)

    elementType( 必选)

    API应与之关联的元素类型的类 NAME 。 内置的工艺元素类型类包括:

    • craftelementsAsset
    • craftelementsCategory
    • craftelementsEntry
    • craftelementsGlobalSet
    • craftelementsMatrixBlock
    • craftelementsTag
    • craftelementsUser
    'elementType'=>craftelementsEntry::class,
    criteria

    应该在元素查询上设置的参数的array,这些参数将获取元素。

    'criteria'=> ['section'=>'news','type'=>'article',],
    transformer

    应该用于定义每个元素应该返回的数据的转换器插件。 如果不设置,将使用默认转换器,其中包括元素属性值的所有直接值,但没有自定义字段值。

    // Can be set to a function'transformer'=>function(craftelementsEntry$entry) {return ['title'=>$entry->title,'id'=>$entry->id,'url'=>$entry->url, ];},// Or a string/array that defines a Transformer class configuration'transformer'=>'MyTransformerClassName',// Or a Transformer class instance'transformer'=>newMyTransformerClassName(),

    自定义转换器类的外观如下所示:

    <?phpusecraftelementsEntry;useLeagueFractalTransformerAbstract;classMyTransformerClassNameextendsTransformerAbstract{publicfunctiontransform(Entry$entry) {return [//.. . ]; }}
    one

    是否只返回第一个匹配元素。 默认情况下设置为 false,这意味着将返回所有匹配的元素。

    'one'=>true,
    paginate

    是否应对结果进行分页。 默认情况下,这将设置为 true,这意味着每个响应中只包含匹配元素的子集,附加元数据。

    'paginate'=>false,
    elementsPerPage

    如果启用分页,则应包含在每个页面中的元素的最大数目。 默认情况下设置为 100.

    'elementsPerPage'=>10,
    pageParam

    应用于标识请求的页的查询字符串参数 NAME 。 默认情况下设置为 'page'

    'pageParam'=>'pg',

    注意,它不能设置为 'p',因为它是参数工艺用来检查请求的路径。

    resourceKey

    元素在响应数据中嵌套的键。 默认情况下,这是 'data'

    'resourceKey'=>'entries',
    meta

    响应数据中应该包含的任何自定义元数据。

    'meta'=> ['description'=>'Recent news from Happy Lager',],
    serializer

    应用于格式化返回数据的序列化程序插件。

    可能的值包括:

    includes

    包含用于当前请求的名称( 如果有的话) 。

    'includes'=>Craft::$app->request->getQueryParam('include'),

    注意,这里设置需要一个已经准备好处理的自定义转换器类,其中包括:

    classMyTransformerClassNameextendsTransformerAbstract{protected$availableIncludes= ['author'];publicfunctionincludeAuthor(Entry$entry) {return$this->item($entry->author, function(User$author) {return ['id'=>$author->id,'name'=>$author->name, ]; }); }//.. .}
    excludes

    包括应该为当前请求排除的名称,否则将包括( 比如 ) 。 如果它们被列为默认包含),则为。

    'excludes'=>'author',

    includes 一样,这个设置需要定制的transformer类。

    jsonOptions

    准备响应时将传递给 json_encode()$options 参数的值。 默认情况 JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE 将被传递。

    'jsonOptions'=>JSON_UNESCAPED_UNICODE,
    pretty

    jsonOptions 添加 JSON_PRETTY_PRINT的快捷方式。

    'pretty'=>true,
    cache

    输出是否应该缓存,以及需要多长时间。

    可能的值包括:

    • false( 默认值) - 结果从不缓存
    • true - 根据 cacheDuration 工艺配置设置指定的持续时间缓存结果
    • 整数- 对给定的秒数缓存结果
    • 一个间隔规范字符串- 结果被缓存为指定的持续时间

    注意 onBeforeSendData 事件不会在缓存启动时被触发。

    'cache'=>'PT1M', // one minute

    动态URL模式和端点配置

    URL模式可以以 <subpatternName:regex> 格式包含动态子模式,其中 subpatternName 是子模式的NAME,regex 是一个有效的正则表达式。 例如,URL Pattern" news/<entryId:d+>.json"将会像 news/100.json 一样,使用 MATCH 。 还可以在正则表达式中使用标记 {handle}{slug},这将用适当的正规表达式 模式替换为匹配句柄和元素 slugs 。

    端点配置也可以是动态的,通过使用函数而不是 array 。 如果这样做,函数应该返回配置设置的array 。 URL Pattern 中的任何子模式 MATCHES 都将映射到函数的参数。 如果 URL Pattern 包含 entryId 子模式,并且端点配置是带有 $entryId 参数的函数,那么URL子表达式将传递给该函数参数。 这使得基于URL子模式 MATCHES 修改生成的端点配置变得很容易。

    'news/<entryId:d+>.json'=>function($entryId) {return ['elementType'=>craftelementsEntry::class,'criteria'=> ['id'=>$entryId],'one'=>true, ];},

    设置默认配置设置

    你可以在 endpoints 键( 在它的内部不包括 ) 旁边添加 defaults 键,为端点配置设置指定默认值。

    usecraftelementsEntry;return ['defaults'=> ['elementType'=>Entry::class,'elementsPerPage'=>10,'pageParam'=>'pg','transformer'=>function(Entry$entry) {return ['title'=>$entry->title,'id'=>$entry->id,'url'=>$entry->url, ]; }, ],'endpoints'=> ['news.json'=> ['criteria'=> ['section'=>'news'], ],'news/<entryId:d+>.json'=>function($entryId) {return ['criteria'=> ['id'=>$entryId],'one'=>true, ]; }, ]];

    条目草稿和版本

    元素API提供了一个特定的分形资源,它添加了 draftIdversionId 配置设置。 要使用它,请将 class 插件配置设置为'craftelementapiresourcesEntryResource'

    如果未设置 draftIdversionId,则它的行为将与默认的分形资源相同。 如果设置了它的中任何一个,则将忽略 criteria 设置,并且只返回请求的输入草稿/版本。

    可能在设置 draftId 或者 versionId 之前,向端点添加一定级别的身份验证是一个好主意。

    'news/<entryId:d+>.json'=>function($entryId) {if ($draftId=Craft::$app->request->getQueryParam('draftId')) {// Make sure they have permission to view drafts$user=Craft::$app->user->getIdentity();if (!$user|| (!$user->admin&&!$user->isInGroup('authors'))) {thrownewyiiwebForbiddenHttpException('You must be an author to access drafts!'); } }return ['class'=>craftelementapiresourcesEntryResource::class,'criteria'=> ['id'=>$entryId],'draftId'=>$draftId,'one'=>true, ];},

    示例

    下面是几个端点示例,它们的响应会是什么样子。

    分页索引终结点

    'ingredients.json'=> ['criteria'=> ['section'=>'ingredients'],'elementsPerPage'=>10,'transformer'=>function(craftelementsEntry$entry) {return ['title'=>$entry->title,'url'=>$entry->url,'jsonUrl'=>UrlHelper::url("ingredients/{$entry->slug}.json"), ]; },'pretty'=>true,],
    {
     "data": [
     {
     "title":"Gin",
     "url":"/ingredients/gin",
     "jsonUrl":"/ingredients/gin.json" },
     {
     "title":"Tonic Water",
     "url":"/ingredients/tonic-water",
     "jsonUrl":"/ingredients/tonic-water.json" },
     //.. . ],
     "meta": {
     "pagination": {
     "total":66,
     "count":10,
     "per_page":10,
     "current_page":1,
     "total_pages":7,
     "links": {
     "next":"/ingredients.json?p=2" }
     }
     }
    }

    单个入口端点

    'ingredients/<slug:{slug}>.json'=>function($slug) {return ['criteria'=> ['section'=>'ingredients','slug'=>$slug ],'one'=>true,'transformer'=>function(craftelementsEntry$entry) {// Create an array of all the photo URLs$photos= [];foreach ($entry->photosas$photo) {$photos[] =$photo->url; }return ['title'=>$entry->title,'url'=>$entry->url,'description'=> (string) $entry->description,'photos'=>$photos ]; },'pretty'=>true, ];},
    {
     "title":"Gin",
     "url":"/ingredients/gin",
     "description":"<p>Gin is a spirit which derives its predominant flavour from juniper berries.</p>",
     "photos": [
     "/images/drinks/GinAndTonic1.jpg" ]
    }

    JSON提要

    下面是如何使用元素API为你的站点设置 JSON提要 ( 。版本 1 ) 。

    请注意 photosbodysummarytags 是虚构的自定义字段。

    'feed.json'=> ['serializer'=>'jsonFeed','elementType'=>craftelementsEntry::class,'criteria'=> ['section'=>'news'],'transformer'=>function(craftelementsEntry$entry) {$image=$entry->photos->first();return ['id'=> (string) $entry->id,'url'=>$entry->url,'title'=>$entry->title,'content_html'=> (string) $entry->body,'summary'=>$entry->summary,'image'=>$image? $image->url : null,'date_published'=>$entry->postDate->format(DateTime::ATOM),'date_modified'=>$entry->dateUpdated->format(DateTime::ATOM),'author'=> ['name'=>$entry->author->name],'tags'=>array_map('strval', $entry->tags->find()), ]; },'meta'=> ['description'=>'Recent news from Happy Lager', ],'pretty'=>true,]
    {
     "version":"https://jsonfeed.org/version/1",
     "title":"Happy Lager",
     "home_page_url":"http://domain.com/",
     "feed_url":"http://domain.com/feed.json",
     "description":"Craft demo site",
     "items": [
     {
     "id":"24",
     "url":"http://domain.com/news/the-future-of-augmented-reality",
     "title":"The Future of Augmented Reality",
     "content_html":"<p>Nam libero tempore, cum soluta nobis est eligendi.. .</p>",
     "date_published":"2016-05-07T00:00:00+00:00",
     "date_modified":"2016-06-03T17:43:36+00:00",
     "author": {
     "name":"Liz Murphy" },
     "tags": [
     "augmented reality",
     "futurism" ]
     },
     {
     "id":"4",
     "url":"http://domain.com/news/barrel-aged-digital-natives",
     "title":"Barrel Aged Digital Natives",
     "content_html":"<p>Nam libero tempore, cum soluta nobis est eligendi.. .</p>",,
     "date_published":"2016-05-06T00:00:00+00:00",
     "date_modified":"2017-05-18T13:20:27+00:00",
     "author": {
     "name":"Liz Murphy" },
     "tags": [
     "barrel-aged" ]
     },
     //.. . ]
    }


    文章标签:API  Json Api  

    Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备05059198号-3  |  如果智培  |  酷兔英语