{"id":233988,"date":"2023-02-26T18:27:00","date_gmt":"2023-02-26T15:27:00","guid":{"rendered":"https:\/\/wordpress.mediadoma.com\/?p=233988"},"modified":"2022-11-11T13:36:27","modified_gmt":"2022-11-11T10:36:27","slug":"criar-e-buscar-endpoints-rest-personalizados-em-blocos-gutenberg","status":"publish","type":"post","link":"https:\/\/wordpress.mediadoma.com\/pt-pt\/criar-e-buscar-endpoints-rest-personalizados-em-blocos-gutenberg\/","title":{"rendered":"Criar e buscar endpoints REST personalizados em blocos Gutenberg"},"content":{"rendered":"\n

Neste post, tentarei criar uma vis\u00e3o geral de como criar endpoints personalizados da API REST e realizar solicita\u00e7\u00f5es para eles em um bloco Gutenberg personalizado. Ou seja, fazer solicita\u00e7\u00f5es com fetch<\/code>m\u00e9todos de informa\u00e7\u00f5es n\u00e3o dispon\u00edveis nos armazenamentos de dados cadastrados do WordPress.<\/p>\n

Um lembrete amig\u00e1vel: as informa\u00e7\u00f5es mais b\u00e1sicas j\u00e1 est\u00e3o dispon\u00edveis nos armazenamentos de dados do WordPress. Por exemplo, consultas b\u00e1sicas de postagens, p\u00e1ginas, tipos de postagem personalizados, taxonomias, autores, m\u00eddia e muito mais est\u00e3o dispon\u00edveis sem a necessidade de criar seus pr\u00f3prios endpoints personalizados. Para acessar essas lojas, voc\u00ea prefere usar o m\u00f3dulo de dados principal do WordPress (withSelect<\/code>e select()<\/code>). Abaixo est\u00e1 uma parte do tutorial que se aprofunda em como fazer isso.<\/p>\n

API REST do WordPress<\/h2>\n

Se voc\u00ea ainda n\u00e3o sabia; A API REST do WordPress \u00e9 uma interface JSON para enviar e receber dados do seu site WordPress. Pode ser usado externamente ou internamente. Com o editor Gutenberg e a mudan\u00e7a para Javascript, os usos da API REST definitivamente aumentaram. A API REST do WordPress tem v\u00e1rios endpoints que podemos usar. Veja uma refer\u00eancia completa sobre todos os endpoints da API REST aqui<\/a>. Voc\u00ea encontrar\u00e1, por exemplo, endpoints para postagens e a maioria dos outros conte\u00fados internos \u2013 tanto para leitura quanto para atualiza\u00e7\u00e3o. Desenvolvedores de temas ou plugins podem registrar seus pr\u00f3prios endpoints personalizados.<\/p>\n

Seu site WordPress tem um URL de API REST raiz, como padr\u00e3o localizado em <your domain>\/wp-json<\/code>. Por exemplo, um WordPress local com a URL http:\/\/localhost\/wordpress\/<\/code>pode acessar a API REST em http:\/\/localhost\/wordpress\/wp-json<\/code>. A partir da\u00ed, precisamos anexar endpoints. Referindo-se \u00e0 refer\u00eancia de endpoints acima, podemos recuperar uma lista de postagens mais recentes no endpoint \/wp\/v2\/posts<\/code>. Isso significa que, se voc\u00ea acessar http:\/\/localhost\/wordpress\/wp-json\/wp\/v2\/posts<\/code>em seu navegador, receber\u00e1 uma resposta formatada em JSON das \u00faltimas postagens em seu site WordPress.<\/p>\n

Uma nota sobre namespaces est\u00e1 em ordem. Um URL da API REST come\u00e7a com um namespace (‘ wp\/v2<\/code>‘ \u00e9 o namespace do WordPress’ como visto nos URLs de exemplo acima). Namespaces \u00e9 um conceito para evitar conflitos no n\u00facleo do WordPress, temas e plugins adicionando endpoints com o mesmo nome. Crie seu pr\u00f3prio namespace exclusivo \u2013 normalmente uma forma de slug do seu tema ou nome do plugin. Ap\u00f3s o slug, uma regra geral \u00e9 adicionar o n\u00famero da vers\u00e3o, normalmente come\u00e7ando na v1. Como exemplo, o slug do meu tema \u00e9 ‘ awhitepixel<\/code>‘, ent\u00e3o se eu fosse criar endpoints personalizados no meu tema eu usaria o namespace ‘ awhitepixel\/v1<\/code>‘. Com este namespace eu poderia registrar um endpoint ‘ posts<\/code>‘ e n\u00e3o causaria problemas mesmo sendo id\u00eantico ao nome do endpoint do WordPress.<\/p>\n

Trabalhar com a API REST no WordPress \u00e9 um t\u00f3pico grande com muitas informa\u00e7\u00f5es boas dispon\u00edveis. Neste post estou focando na usabilidade no editor Gutenberg e como recuper\u00e1-los em Javascript.<\/p>\n

O que faremos e o que precisamos<\/h2>\n

A usabilidade para solicitar informa\u00e7\u00f5es personalizadas tem uma ampla variedade de casos de uso, portanto, voc\u00ea geralmente precisa personalizar os exemplos de c\u00f3digo abaixo para atender \u00e0s suas necessidades. Os dados podem ser uma consulta de postagem personalizada, uma consulta SQL personalizada ou algo completamente diferente.<\/p>\n

Quando criamos um endpoint personalizado, temos controle total sobre seu retorno. Podemos realizar qualquer tipo de opera\u00e7\u00e3o e consulta no WordPress\/PHP e passar isso como JSON. E no nosso bloco Gutenberg poderemos recuperar esse retorno e fazer o que quisermos com ele dentro da edit<\/code>fun\u00e7\u00e3o do bloco. Normalmente, voc\u00ea usaria os dados para apresentar ao usu\u00e1rio final uma op\u00e7\u00e3o ou informa\u00e7\u00e3o no editor de blocos, mas tamb\u00e9m pode armazenar informa\u00e7\u00f5es deles em seu bloco para uso posterior. Voc\u00ea tamb\u00e9m pode criar seus pr\u00f3prios armazenamentos personalizados para esses dados, mas n\u00e3o vou entrar em como fazer isso.<\/p>\n

Suponho que voc\u00ea j\u00e1 esteja familiarizado com como criar blocos personalizados do Gutenberg, ent\u00e3o n\u00e3o vou detalhar isso aqui.<\/p>\n

Como criar um endpoint da API REST<\/h2>\n

O registro de um endpoint de API REST personalizado \u00e9 feito em PHP. Voc\u00ea adicionaria esse c\u00f3digo no seu tema functions.php<\/code>ou em um c\u00f3digo de plug-in ativo. Conecte uma fun\u00e7\u00e3o \u00e0 a\u00e7\u00e3o rest_api_init<\/code>e execute a fun\u00e7\u00e3o [register_rest_route](https:\/\/developer.wordpress.org\/reference\/functions\/register_rest_route\/)()<\/code>para cada endpoint que voc\u00ea deseja registrar.<\/p>\n

Forne\u00e7a seu namespace como primeiro par\u00e2metro, sua rota de endpoint como segundo e uma matriz de configura\u00e7\u00f5es como terceiro par\u00e2metro para register_rest_route()<\/code>. O quarto par\u00e2metro controla se voc\u00ea deseja ou n\u00e3o substituir uma rota existente; n\u00e3o \u00e9 algo que veremos aqui. No array para o terceiro par\u00e2metro voc\u00ea deve no m\u00ednimo definir a propriedade ‘ callback<\/code>‘ para uma fun\u00e7\u00e3o que seja respons\u00e1vel por retornar os dados do endpoint. Definir ‘ method<\/code>‘ tamb\u00e9m \u00e9 comum, por exemplo, definir seu ponto de extremidade como ‘ GET<\/code>‘, ‘ POST<\/code>‘, ‘ PUT<\/code>‘, etc.<\/p>\n

Vamos come\u00e7ar registrando um endpoint simples;<\/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
O namespace do meu tema \u00e9 ‘ awhitepixel\/v1<\/code>‘ e estou registrando um endpoint ‘ mydata<\/code>‘ dentro deste namespace. Isso significa que posso acessar minha API REST personalizada em http:\/\/localhost\/wordpress\/wp-json\/awhitepixel\/v1\/mydata<\/code>.<\/p>\n
Ao registrar (ou alterar) as rotas da API REST, voc\u00ea precisar\u00e1 liberar seus permalinks<\/strong> para que funcione. Voc\u00ea pode fazer isso visitando Configura\u00e7\u00f5es > Permalinks e simplesmente clicando em Salvar.<\/p>\n
O c\u00f3digo acima ainda n\u00e3o funciona, pois n\u00e3o defini a fun\u00e7\u00e3o definida como callback: awhitepixel_rest_route_mydata<\/code>. A fun\u00e7\u00e3o de retorno de chamada recebe um par\u00e2metro; uma matriz de dados com informa\u00e7\u00f5es e argumentos passados \u200b\u200bda solicita\u00e7\u00e3o. Finalmente, voc\u00ea precisa considerar cuidadosamente o retorno da sua fun\u00e7\u00e3o de retorno de chamada.<\/p>\n
Em primeiro lugar, voc\u00ea deve sempre retornar algo de seu retorno de chamada de endpoint. Qualquer retorno ser\u00e1 automaticamente convertido em JSON pelo WordPress. Isso significa que voc\u00ea pode retornar praticamente qualquer forma de dados em sua fun\u00e7\u00e3o; uma string, null, uma matriz ou [WP_Error](https:\/\/developer.wordpress.org\/reference\/classes\/wp_error\/)<\/code>inst\u00e2ncia. Voc\u00ea tamb\u00e9m pode optar por retornar um [WP_REST_Response](https:\/\/developer.wordpress.org\/reference\/classes\/wp_rest_response\/)<\/code>objeto para ter mais controle sobre, por exemplo, c\u00f3digo de status ou informa\u00e7\u00f5es de cabe\u00e7alho. Eu recomendo envolver o retorno na fun\u00e7\u00e3o [rest_ensure_response](https:\/\/developer.wordpress.org\/reference\/functions\/rest_ensure_response\/)()<\/code>para garantir que sua resposta seja uma resposta REST v\u00e1lida.<\/p>\n
Vamos definir nossa fun\u00e7\u00e3o de retorno de chamada e retornar uma string simples como in\u00edcio;<\/p>\n
function awhitepixel_rest_route_mydata($data) {\n    $response = 'Hello there!';\n    return rest_ensure_response($response);\n}<\/code><\/pre>\n
Com o c\u00f3digo acima (e permalinks liberados), agora posso ir para o URL http:\/\/localhost\/wordpress\/wp-json\/awhitepixel\/v1\/mydata<\/code>.<\/p>\n
\"Criar<\/a><\/p>\n
A partir daqui, podemos adicionar qualquer tipo de c\u00f3digo em nossa fun\u00e7\u00e3o de retorno de chamada para gerar os dados adequados para retornar. Voc\u00ea pode consultar o conte\u00fado do WordPress com, por exemplo [WP_Query](https:\/\/developer.wordpress.org\/reference\/classes\/wp_query\/)<\/code>, fazer consultas no banco de dados ou solicitar dados externos. Esta parte \u00e9 com voc\u00ea.<\/p>\n
Agora, vamos para o lado oposto; como fazer os pedidos.<\/p>\n
Fazendo solicita\u00e7\u00f5es de API REST em Javascript<\/h2>\n
A execu\u00e7\u00e3o da solicita\u00e7\u00e3o REST geralmente \u00e9 feita usando [fetch](https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/API\/Fetch_API)<\/code>Javascript. O WordPress fornece seu pr\u00f3prio wrapper fetch<\/code>que simplifica as solicita\u00e7\u00f5es da API REST do WordPress; [wp.apiFetch](https:\/\/developer.wordpress.org\/block-editor\/packages\/packages-api-fetch\/)<\/code>. Isto \u00e9 o que vou usar no meu bloco Gutenberg personalizado. Lembre-se de que uma fetch<\/code>solicita\u00e7\u00e3o retorna uma “promessa" \u2013 portanto, precisamos encadear a .then()<\/code>para lidar com o retorno da solicita\u00e7\u00e3o real. O uso b\u00e1sico \u00e9 algo assim;<\/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>nos permite fornecer uma path<\/code>propriedade em vez de construir o URL completo. Tudo o que precisamos fornecer \u00e9 o namespace e o endpoint, e apiFetch<\/code>anexaremos isso ao URL raiz da API REST do WordPress. Dentro da .then()<\/code>fun\u00e7\u00e3o temos acesso aos dados que j\u00e1 est\u00e3o convertidos para JSON. \u00c9 aqui que voc\u00ea faria algo com os dados. Normalmente voc\u00ea armazenaria os dados retornados, por exemplo, no estado do componente.<\/p>\n
Abaixo est\u00e1 um exemplo de edit<\/code>componente de um bloco Gutenberg personalizado. \u00c9 baseado em classe para ser usado state<\/code>para armazenar os dados retornados da solicita\u00e7\u00e3o da API REST. Isso tamb\u00e9m nos permite executar a solicita\u00e7\u00e3o componentDidMount()<\/code>quando ela \u00e9 montada pela primeira vez (consulte a documenta\u00e7\u00e3o do React sobre m\u00e9todos de ciclo de vida<\/a> ). Tudo isso fornece um exemplo simples para voc\u00ea entender o conceito b\u00e1sico; n\u00e3o como uma receita para fazer exatamente assim. Voc\u00ea pode considerar usar ganchos e componentes funcionais do React<\/a> ou construir um componente de ordem superior<\/a>.<\/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
O exemplo acima \u00e9 um composto baseado em classe que \u00e9 fornecido \u00e0 edit<\/code>fun\u00e7\u00e3o do bloco em registerBlockType()<\/code>. Ele configura um objeto de estado de uma matriz para armazenar os dados (isso depende dos dados que voc\u00ea retorna, obviamente) e um booleano de status para saber quando a solicita\u00e7\u00e3o ass\u00edncrona retornou. Uma vez que o componente \u00e9 montado (renderizado pela primeira vez) ele executa a fun\u00e7\u00e3o para realizar a apiFetch<\/code>requisi\u00e7\u00e3o. Definimos o caminho para o endpoint que registramos no PHP acima. O m\u00e9todo \u00e9 por padr\u00e3o GET, ent\u00e3o n\u00e3o precisamos especificar isso em apiFetch<\/code>. E dentro .then()<\/code>da fun\u00e7\u00e3o quando a requisi\u00e7\u00e3o est\u00e1 pronta atualizamos o estado do componente com os dados retornados.<\/p>\n
Obviamente, a fun\u00e7\u00e3o de renderiza\u00e7\u00e3o do seu bloco faria mais com os pr\u00f3prios dados retornados. Voc\u00ea pode querer fornecer os dados ao usu\u00e1rio de alguma forma apresentando uma lista para talvez escolher. Tudo depende de que tipo de dados s\u00e3o e para que voc\u00ea deseja us\u00e1-los.<\/p>\n
Passando argumentos para o endpoint<\/h2>\n
Em alguns casos, precisamos passar alguns argumentos para o endpoint. Os usos comuns s\u00e3o passar um ID ap\u00f3s o terminal; por exemplo http:\/\/localhost\/wordpress\/wp-json\/wp\/v2\/posts\/14<\/code>, retornaria o ID de postagem 14.<\/p>\n
Isso \u00e9 bem simples e \u00e9 feito adicionando um padr\u00e3o de pesquisa regex ao endpoint ao registr\u00e1-lo. Requer algum conhecimento de regexes para construir padr\u00f5es complexos, mas abaixo est\u00e1 um exemplo que corresponde a um n\u00famero e atribui a ele o nome ‘id’. Nomear as correspond\u00eancias nos d\u00e1 meios de acessar a vari\u00e1vel em nossa fun\u00e7\u00e3o de retorno de chamada. Deixe-me mostrar o que quero dizer.<\/p>\n
Vamos registrar uma nova rota de endpoint. Usamos o mesmo endpoint que fizemos anteriormente (‘ awhitepixel\/v1\/mydata<\/code>‘), mas para essa rota adicionamos uma correspond\u00eancia de regex para um n\u00famero no final.<\/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
O padr\u00e3o regex (?P<id>[d]+)<\/code>parece enigm\u00e1tico, mas ficar\u00e1 bem claro com algum entendimento b\u00e1sico de regex. A [d]+<\/code>parte corresponde a qualquer n\u00famero (0-9) 1 ou mais vezes. As partes (?P<id><\/code>e )<\/code>s\u00e3o para corresponder a um grupo nomeado. O nome do grupo \u00e9 neste caso id<\/code>, mas voc\u00ea pode nomear seu(s) grupo(s) como quiser.<\/p>\n
Voc\u00ea pode optar por direcionar esse endpoint para uma fun\u00e7\u00e3o de retorno de chamada separada, mas optei por usar a mesma fun\u00e7\u00e3o para lidar com solicita\u00e7\u00f5es \/mydata<\/code>e \/mydata\/<ID><\/code>solicita\u00e7\u00f5es. Isso significa que eu posso na minha fun\u00e7\u00e3o de callback fazer:<\/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
Lembre-se de que o par\u00e2metro para a fun\u00e7\u00e3o de retorno de chamada cont\u00e9m os argumentos retornados. Como nomeei meu grupo correspondente como ‘ id<\/code>‘, o valor correspondente estar\u00e1 acess\u00edvel em $data['id']<\/code>. E, finalmente, como uso a mesma fun\u00e7\u00e3o para lidar com solicita\u00e7\u00f5es com e sem ID, posso alternar facilmente entre os dois retornos diferentes.<\/p>\n
Com isso (e links permanentes atualizados), obterei essas respostas para meus endpoints personalizados:<\/p>\n
\"Criar<\/a>\"Criar<\/a><\/p>\n
Fonte de grava\u00e7\u00e3o:  awhitepixel.com<\/a><\/div><\/p>\n","protected":false},"excerpt":{"rendered":"
Um guia sobre como criar endpoints personalizados da API REST do WordPress e executar solicita\u00e7\u00f5es apiFetch para eles em um bloco Gutenberg personalizado.<\/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":[898,898,837,941,941,920,1110,920,816,816,837,846,846,867,867],"tags":[1170],"class_list":["post-233988","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-codigo-2","category-guia-para-iniciantes","category-gutenberg-8","category-outro","category-n-a","category-plug-ins","category-tutoriais","category-wordpress-8","tag-affiai-pt-pt"],"_links":{"self":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/posts\/233988","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/comments?post=233988"}],"version-history":[{"count":0,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/posts\/233988\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/media\/224922"}],"wp:attachment":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/media?parent=233988"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/categories?post=233988"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/tags?post=233988"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}