{"id":234276,"date":"2023-02-26T18:10:00","date_gmt":"2023-02-26T15:10:00","guid":{"rendered":"https:\/\/wordpress.mediadoma.com\/?p=234276"},"modified":"2022-11-12T03:19:25","modified_gmt":"2022-11-12T00:19:25","slug":"creer-et-recuperer-des-points-de-terminaison-rest-personnalises-dans-les-blocs-gutenberg","status":"publish","type":"post","link":"https:\/\/wordpress.mediadoma.com\/fr\/creer-et-recuperer-des-points-de-terminaison-rest-personnalises-dans-les-blocs-gutenberg\/","title":{"rendered":"Cr\u00e9er et r\u00e9cup\u00e9rer des points de terminaison REST personnalis\u00e9s dans les blocs Gutenberg"},"content":{"rendered":"\n

Dans cet article, je vais essayer de cr\u00e9er un aper\u00e7u de la fa\u00e7on de cr\u00e9er des points de terminaison d’API REST personnalis\u00e9s et d’effectuer des demandes pour eux dans un bloc Gutenberg personnalis\u00e9. C’est-\u00e0-dire, faire des demandes avec des fetch<\/code>m\u00e9thodes d’informations non disponibles dans les magasins de donn\u00e9es enregistr\u00e9s de WordPress.<\/p>\n

Un rappel amical\u00a0: la plupart des informations de base sont d\u00e9j\u00e0 disponibles dans les magasins de donn\u00e9es de WordPress. Par exemple, les requ\u00eates de base sur les publications, les pages, les types de publication personnalis\u00e9s, les taxonomies, les auteurs, les m\u00e9dias, etc. sont disponibles telles quelles sans avoir \u00e0 cr\u00e9er vos propres points de terminaison personnalis\u00e9s. Pour acc\u00e9der \u00e0 ces magasins, vous pr\u00e9f\u00e9rez utiliser le module de donn\u00e9es de base de WordPress (withSelect<\/code>et select()<\/code>). Vous trouverez ci-dessous une partie du didacticiel qui explique en profondeur comment proc\u00e9der.<\/p>\n

API REST WordPress<\/h2>\n

Si vous ne le saviez pas d\u00e9j\u00e0; WordPress REST API est une interface JSON pour envoyer et recevoir des donn\u00e9es de votre site WordPress. Il peut \u00eatre utilis\u00e9 en externe ou en interne. Avec l’\u00e9diteur Gutenberg et le passage \u00e0 Javascript, les utilisations de l’API REST ont d\u00e9finitivement augment\u00e9. L’API REST WordPress a tout un tas de points de terminaison que nous pouvons utiliser. Consultez une r\u00e9f\u00e9rence compl\u00e8te sur tous les points de terminaison de l’API REST ici<\/a>. Vous trouverez par exemple des points de terminaison pour les publications et la plupart des autres contenus internes, \u00e0 la fois pour la lecture et la mise \u00e0 jour. Les d\u00e9veloppeurs de th\u00e8mes ou de plugins peuvent enregistrer leurs propres points de terminaison personnalis\u00e9s.<\/p>\n

Votre site WordPress a une URL d’API REST racine, par d\u00e9faut situ\u00e9e \u00e0 <your domain>\/wp-json<\/code>. Par exemple, un WordPress local avec l’URL http:\/\/localhost\/wordpress\/<\/code>peut acc\u00e9der \u00e0 l’API REST \u00e0 l’adresse http:\/\/localhost\/wordpress\/wp-json<\/code>. \u00c0 partir de l\u00e0, nous devons ajouter des points de terminaison. En se r\u00e9f\u00e9rant \u00e0 la r\u00e9f\u00e9rence ci-dessus des points de terminaison, nous pouvons r\u00e9cup\u00e9rer une liste des derniers messages dans le point de terminaison \/wp\/v2\/posts<\/code>. Cela signifie que si vous acc\u00e9dez \u00e0 http:\/\/localhost\/wordpress\/wp-json\/wp\/v2\/posts<\/code>votre navigateur, vous obtiendrez une r\u00e9ponse au format JSON des derniers messages de votre site WordPress.<\/p>\n

Une note sur les espaces de noms s’impose. Une URL d’API REST commence par un espace de noms (‘ wp\/v2<\/code>‘ est l’espace de noms de WordPress, comme indiqu\u00e9 dans les exemples d’URL ci-dessus). Les espaces de noms sont un concept permettant d’\u00e9viter les conflits dans le c\u0153ur de WordPress, les th\u00e8mes et les plugins ajoutant des points de terminaison portant le m\u00eame nom. Cr\u00e9ez votre propre espace de noms unique – g\u00e9n\u00e9ralement une forme slug de votre nom de th\u00e8me ou de plugin. Apr\u00e8s le slug, une r\u00e8gle g\u00e9n\u00e9rale consiste \u00e0 ajouter le num\u00e9ro de version, commen\u00e7ant normalement \u00e0 v1. Par exemple, le slug de mon th\u00e8me est ‘ awhitepixel<\/code>‘, donc si je devais cr\u00e9er des points de terminaison personnalis\u00e9s dans mon th\u00e8me, j’utiliserais l’espace de noms ‘ awhitepixel\/v1<\/code>‘. Avec cet espace de noms, je pourrais enregistrer un point de terminaison ‘ posts<\/code>‘ et cela ne poserait aucun probl\u00e8me m\u00eame s’il est identique au nom du point de terminaison de WordPress.<\/p>\n

Travailler avec l’API REST dans WordPress est un vaste sujet avec beaucoup de bonnes informations disponibles. Dans cet article, je me concentre sur la convivialit\u00e9 dans l’\u00e9diteur Gutenberg et sur la fa\u00e7on de les r\u00e9cup\u00e9rer en Javascript.<\/p>\n

Ce que nous ferons, et ce dont nous avons besoin<\/h2>\n

La facilit\u00e9 d’utilisation pour demander des informations personnalis\u00e9es a un large \u00e9ventail de cas d’utilisation, vous devrez donc g\u00e9n\u00e9ralement personnaliser les exemples de code ci-dessous pour r\u00e9pondre \u00e0 vos besoins. Les donn\u00e9es peuvent \u00eatre une requ\u00eate de publication personnalis\u00e9e, une requ\u00eate SQL personnalis\u00e9e ou quelque chose de compl\u00e8tement diff\u00e9rent.<\/p>\n

Lorsque nous cr\u00e9ons un point de terminaison personnalis\u00e9, nous contr\u00f4lons totalement son retour. Nous pouvons effectuer tout type d’op\u00e9rations et de requ\u00eates dans WordPress\/PHP et les transmettre au format JSON. Et dans notre bloc Gutenberg, nous pourrons r\u00e9cup\u00e9rer ce retour et en faire ce que nous voulons dans la edit<\/code>fonction du bloc. En r\u00e8gle g\u00e9n\u00e9rale, vous utiliserez les donn\u00e9es pour pr\u00e9senter \u00e0 l’utilisateur final un choix ou des informations dans l’\u00e9diteur de blocs, mais vous pouvez \u00e9galement stocker des informations dans votre bloc pour une utilisation ult\u00e9rieure. Vous pouvez \u00e9galement cr\u00e9er vos propres magasins personnalis\u00e9s pour ces donn\u00e9es, mais je n’expliquerai pas comment proc\u00e9der.<\/p>\n

Je suppose que vous savez d\u00e9j\u00e0 comment cr\u00e9er des blocs Gutenberg personnalis\u00e9s, je ne vais donc pas d\u00e9tailler cela ici.<\/p>\n

Cr\u00e9ation d’un point de terminaison d’API REST<\/h2>\n

L’enregistrement d’un point de terminaison d’API REST personnalis\u00e9 se fait en PHP. Vous ajouteriez ce code dans votre th\u00e8me functions.php<\/code>ou dans un code de plugin actif. Accrochez une fonction \u00e0 l’ action rest_api_init<\/code>et ex\u00e9cutez la fonction [register_rest_route](https:\/\/developer.wordpress.org\/reference\/functions\/register_rest_route\/)()<\/code>pour chaque point de terminaison que vous souhaitez enregistrer.<\/p>\n

Fournissez votre espace de noms comme premier param\u00e8tre, votre itin\u00e9raire de point de terminaison comme deuxi\u00e8me et un tableau de param\u00e8tres comme troisi\u00e8me param\u00e8tre \u00e0 register_rest_route()<\/code>. Le quatri\u00e8me param\u00e8tre contr\u00f4le si vous souhaitez ou non remplacer une route existante\u00a0; pas quelque chose que nous allons regarder ici. Dans le tableau du troisi\u00e8me param\u00e8tre, vous devez au minimum d\u00e9finir la propri\u00e9t\u00e9 ‘ callback<\/code>‘ sur une fonction charg\u00e9e de renvoyer les donn\u00e9es du point de terminaison. La d\u00e9finition de ‘ method<\/code>‘ est \u00e9galement courante, par exemple, la d\u00e9finition de votre point de terminaison sur ‘ GET<\/code>‘, ‘ POST<\/code>‘, ‘ PUT<\/code>‘, etc.<\/p>\n

Commen\u00e7ons par enregistrer un point de terminaison simple\u00a0;<\/p>\n

add_action('rest_api_init', function() {\n    register_rest_route('awhitepixel\/v1', '\/mydata', [\n        'method' => 'GET',\n        'callback' => 'awhitepixel_rest_route_mydata'\n    ]);\n});<\/code><\/pre>\n
L’espace de noms de mon th\u00e8me est ‘ awhitepixel\/v1<\/code>‘ et j’enregistre un point de terminaison ‘ mydata<\/code>‘ dans cet espace de noms. Cela signifie que je peux acc\u00e9der \u00e0 mon API REST personnalis\u00e9e sur http:\/\/localhost\/wordpress\/wp-json\/awhitepixel\/v1\/mydata<\/code>.<\/p>\n
Lors de l’enregistrement (ou de la modification) des routes de l’API REST, vous devrez vider vos permaliens<\/strong> pour que cela fonctionne. Vous pouvez le faire en visitant Param\u00e8tres> Permaliens et cliquez simplement sur Enregistrer.<\/p>\n
Le code ci-dessus ne fonctionne pas encore, car je n’ai pas d\u00e9fini la fonction d\u00e9finie comme rappel\u00a0: awhitepixel_rest_route_mydata<\/code>. La fonction de rappel re\u00e7oit un param\u00e8tre\u00a0; un tableau de donn\u00e9es avec des informations et des arguments transmis \u00e0 partir de la requ\u00eate. Enfin, vous devez examiner attentivement le retour de votre fonction de rappel.<\/p>\n
Tout d’abord, vous devez toujours renvoyer quelque chose \u00e0 partir de votre rappel de point de terminaison. Tout retour sera automatiquement converti en JSON par WordPress. Cela signifie que vous pouvez renvoyer pratiquement n’importe quelle forme de donn\u00e9es dans votre fonction ; une cha\u00eene, null, un tableau ou une [WP_Error](https:\/\/developer.wordpress.org\/reference\/classes\/wp_error\/)<\/code>instance. Vous pouvez \u00e9galement choisir de renvoyer un [WP_REST_Response](https:\/\/developer.wordpress.org\/reference\/classes\/wp_rest_response\/)<\/code>objet pour plus de contr\u00f4le, par exemple sur le code d’\u00e9tat ou les informations d’en-t\u00eate. Je recommande d’envelopper le retour dans la fonction [rest_ensure_response](https:\/\/developer.wordpress.org\/reference\/functions\/rest_ensure_response\/)()<\/code>pour vous assurer que votre r\u00e9ponse est une r\u00e9ponse REST valide.<\/p>\n
D\u00e9finissons notre fonction de rappel et renvoyons une cha\u00eene simple comme d\u00e9but\u00a0;<\/p>\n
function awhitepixel_rest_route_mydata($data) {\n    $response = 'Hello there!';\n    return rest_ensure_response($response);\n}<\/code><\/pre>\n
Avec le code ci-dessus (et les permaliens vid\u00e9s), je peux maintenant acc\u00e9der \u00e0 l’URL http:\/\/localhost\/wordpress\/wp-json\/awhitepixel\/v1\/mydata<\/code>.<\/p>\n
\"Cr\u00e9er<\/a><\/p>\n
\u00c0 partir de l\u00e0, nous pouvons ajouter n’importe quel type de code dans notre fonction de rappel pour g\u00e9n\u00e9rer les donn\u00e9es appropri\u00e9es \u00e0 renvoyer. Vous pouvez interroger le contenu WordPress avec par exemple [WP_Query](https:\/\/developer.wordpress.org\/reference\/classes\/wp_query\/)<\/code>, effectuer des requ\u00eates dans la base de donn\u00e9es ou demander des donn\u00e9es externes. Cette partie d\u00e9pend de vous.<\/p>\n
Maintenant, passons du c\u00f4t\u00e9 oppos\u00e9\u00a0; comment faire les demandes.<\/p>\n
Faire des requ\u00eates API REST en Javascript<\/h2>\n
L’ex\u00e9cution d’une requ\u00eate REST est g\u00e9n\u00e9ralement effectu\u00e9e \u00e0 l’aide [fetch](https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/API\/Fetch_API)<\/code>de Javascript. WordPress fournit son propre wrapper fetch<\/code>qui simplifie les requ\u00eates de l’API WordPress REST ; [wp.apiFetch](https:\/\/developer.wordpress.org\/block-editor\/packages\/packages-api-fetch\/)<\/code>. C’est ce que je vais utiliser dans mon bloc Gutenberg personnalis\u00e9. Gardez \u00e0 l’esprit que les fetch<\/code>requ\u00eates renvoient une "promesse" – nous devons donc encha\u00eener a .then()<\/code>afin de g\u00e9rer le retour r\u00e9el de la requ\u00eate. L’utilisation de base ressemble \u00e0 ceci\u00a0;<\/p>\n
wp.apiFetch({\n    path: '<namespace and endpoint>',\n}).then(data => {\n    console.log('response from apifetch: ', data);\n});<\/code><\/pre>\n
apiFetch<\/code>nous permet de fournir une path<\/code>propri\u00e9t\u00e9 au lieu de construire l’URL compl\u00e8te. Tout ce que nous devons fournir est l’espace de noms et le point de terminaison, et apiFetch<\/code>nous les ajouterons \u00e0 l’URL racine de l’API REST de WordPress. Dans la .then()<\/code>fonction, nous avons acc\u00e8s aux donn\u00e9es d\u00e9j\u00e0 converties en JSON. C’est ici que vous feriez quelque chose avec les donn\u00e9es. Habituellement, vous stockez les donn\u00e9es renvoy\u00e9es, par exemple dans l’\u00e9tat du composant.<\/p>\n
Vous trouverez ci-dessous un exemple de composant de bloc Gutenberg personnalis\u00e9 edit<\/code>. Il est bas\u00e9 sur les classes afin d’\u00eatre utilis\u00e9 state<\/code>pour stocker les donn\u00e9es renvoy\u00e9es par la demande d’API REST. Cela nous permet \u00e9galement d’ex\u00e9cuter la requ\u00eate componentDidMount()<\/code>lors de son premier montage (voir la documentation de React sur les m\u00e9thodes de cycle de vie<\/a> ). Tout cela fournit un exemple simple pour que vous compreniez le concept de base\u00a0; pas comme une recette pour le faire exactement comme \u00e7a. Vous pouvez envisager d’utiliser des crochets React et des composants fonctionnels<\/a> ou de construire un composant d’ordre sup\u00e9rieur \u00e0 la<\/a> place.<\/p>\n
const { Component } = wp.element;\nconst { Spinner } = wp.components;\n\u00a0\nclass BlockEdit extends Component {\n    constructor(props) {\n        super(props);\n        this.state = {\n            list: [],\n            loading: true\n        }\n    }\n\u00a0\n    componentDidMount() {\n        this.runApiFetch();\n    }\n\u00a0\n    runApiFetch() {\n        wp.apiFetch({\n            path: 'awhitepixel\/v1\/mydata',\n        }).then(data => {\n            this.setState({\n                list: data,\n                loading: false\n            });\n        });\n    }\n\u00a0\n    render() {\n        return(\n            <div>\n                {this.state.loading? (<Spinner \/>\n                ): (<p>Data is ready!<\/p>\n                )}\n            <\/div>\n        );\n\u00a0\n    }\n}\nexport default BlockEdit;<\/code><\/pre>\n
L’exemple ci-dessus est un composant bas\u00e9 sur une classe qui est fourni \u00e0 la edit<\/code>fonction du bloc dans registerBlockType()<\/code>. Il configure un objet d’\u00e9tat d’un tableau pour contenir les donn\u00e9es (cela d\u00e9pend des donn\u00e9es que vous renvoyez, \u00e9videmment), et un bool\u00e9en d’\u00e9tat pour savoir quand la requ\u00eate asynchrone est retourn\u00e9e. Une fois que le composant est mont\u00e9 (rendu pour la premi\u00e8re fois), il ex\u00e9cute la fonction pour effectuer la apiFetch<\/code>requ\u00eate. Nous d\u00e9finissons le chemin vers le point de terminaison que nous avons enregistr\u00e9 en PHP ci-dessus. La m\u00e9thode est GET par d\u00e9faut, nous n’avons donc pas besoin de le sp\u00e9cifier dans apiFetch<\/code>. Et \u00e0 l’int\u00e9rieur .then()<\/code>de la fonction lorsque la requ\u00eate est pr\u00eate, nous mettons \u00e0 jour l’\u00e9tat du composant avec les donn\u00e9es renvoy\u00e9es.<\/p>\n
De toute \u00e9vidence, la fonction de rendu de votre bloc ferait plus avec les donn\u00e9es renvoy\u00e9es elles-m\u00eames. Vous voudrez peut-\u00eatre fournir les donn\u00e9es \u00e0 l’utilisateur en pr\u00e9sentant d’une mani\u00e8re ou d’une autre une liste parmi laquelle choisir. Tout d\u00e9pend du type de donn\u00e9es dont il s’agit et de l’utilisation que vous souhaitez en faire.<\/p>\n
Passer des arguments au point de terminaison<\/h2>\n
Dans certains cas, nous devons transmettre certains arguments au point de terminaison. Les utilisations courantes consistent \u00e0 transmettre un ID apr\u00e8s le point de terminaison\u00a0; par exemple http:\/\/localhost\/wordpress\/wp-json\/wp\/v2\/posts\/14<\/code>renverrait l’ID de poste 14.<\/p>\n
C’est assez simple et se fait en ajoutant un mod\u00e8le de recherche regex au point de terminaison lors de son enregistrement. Cela n\u00e9cessite une certaine connaissance des expressions r\u00e9guli\u00e8res pour cr\u00e9er des mod\u00e8les complexes, mais ci-dessous se trouve un exemple qui correspond \u00e0 un nombre et lui attribue le nom "id". Nommer les correspondances nous donne les moyens d’acc\u00e9der \u00e0 la variable dans notre fonction de rappel. Laissez-moi vous montrer ce que je veux dire.<\/p>\n
Enregistrons une nouvelle route de point de terminaison. Nous utilisons le m\u00eame point de terminaison que pr\u00e9c\u00e9demment (‘ awhitepixel\/v1\/mydata<\/code>‘) mais pour cette route, nous ajoutons une correspondance regex pour un nombre \u00e0 la fin.<\/p>\n
add_action('rest_api_init', function() {\n    register_rest_route('awhitepixel\/v1', '\/mydata', [\n        'method' => 'GET',\n        'callback' => 'awhitepixel_rest_route_mydata'\n    ]);\n\u00a0\n    register_rest_route('awhitepixel\/v1', '\/mydata\/(?P<id>[d]+)', [\n        'method' => 'GET',\n        'callback' => 'awhitepixel_rest_route_mydata'\n    ]);\n});<\/code><\/pre>\n
Le mod\u00e8le regex (?P<id>[d]+)<\/code>semble cryptique, mais sera assez clair avec une compr\u00e9hension de base de regex. La [d]+<\/code>partie correspond \u00e0 n’importe quel nombre (0-9) 1 ou plusieurs fois. Les parties (?P<id><\/code>et )<\/code>correspondent \u00e0 un groupe nomm\u00e9. Le nom du groupe est dans ce cas id<\/code>, mais vous pouvez nommer votre ou vos groupes comme vous le souhaitez.<\/p>\n
Vous pouvez choisir de diriger ce point de terminaison vers une fonction de rappel distincte, mais j’ai choisi d’utiliser la m\u00eame fonction pour g\u00e9rer les requ\u00eates \/mydata<\/code>et. \/mydata\/<ID><\/code>Cela signifie que je peux dans ma fonction de rappel faire\u00a0:<\/p>\n
function awhitepixel_rest_route_mydata($data) {\n    if ($data['id']) {\n        $response = 'Create return for ID: '. $data['id'];\n    } else {\n        $response = 'Create general return (no ID provided)';\n    }\n    return rest_ensure_response($response);\n}<\/code><\/pre>\n
N’oubliez pas que le param\u00e8tre de la fonction de rappel contient les arguments renvoy\u00e9s. Parce que j’ai nomm\u00e9 mon groupe correspondant ‘ id<\/code>‘, la valeur correspondante sera accessible dans $data['id']<\/code>. Et enfin parce que j’utilise la m\u00eame fonction pour g\u00e9rer les requ\u00eates avec et sans ID, je peux facilement basculer entre les deux retours diff\u00e9rents.<\/p>\n
Avec ceci (et des permaliens actualis\u00e9s), j’obtiendrai ces r\u00e9ponses pour mes points de terminaison personnalis\u00e9s\u00a0:<\/p>\n
\"Cr\u00e9er<\/a>\"Cr\u00e9er<\/a><\/p>\n
Source d’enregistrement:  awhitepixel.com<\/a><\/div><\/p>\n","protected":false},"excerpt":{"rendered":"
Un guide sur la fa\u00e7on de cr\u00e9er des points de terminaison d’API REST WordPress personnalis\u00e9s et d’effectuer des requ\u00eates apiFetch pour eux dans un bloc Gutenberg personnalis\u00e9.<\/p>\n","protected":false},"author":1,"featured_media":224922,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":"","_wp_rev_ctl_limit":""},"categories":[915,893,893,832,936,936,915,1110,811,811,832,841,841,862,862],"tags":[1167],"class_list":{"0":"post-234276","1":"post","2":"type-post","3":"status-publish","4":"format-standard","5":"has-post-thumbnail","6":"hentry","7":"category-autre","8":"category-code-2","10":"category-guide-pour-les-debutants","11":"category-gutenberg-3","14":"category-n-a","15":"category-plugins-2","18":"category-tutoriels","20":"category-wordpress-3","22":"tag-affiai-fr"},"_links":{"self":[{"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/posts\/234276","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/comments?post=234276"}],"version-history":[{"count":0,"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/posts\/234276\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/media\/224922"}],"wp:attachment":[{"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/media?parent=234276"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/categories?post=234276"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/fr\/wp-json\/wp\/v2\/tags?post=234276"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}