From d4cfb93dc8bfc968efa89be24dce5586f16fa2dc Mon Sep 17 00:00:00 2001 From: Davidson Alencar Date: Wed, 17 Jun 2015 17:01:01 -0300 Subject: [PATCH] docs/guide-pt-BR/rest-controllers.md - translate [ci skip] --- docs/guide-pt-BR/rest-controllers.md | 129 +++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/guide-pt-BR/rest-controllers.md diff --git a/docs/guide-pt-BR/rest-controllers.md b/docs/guide-pt-BR/rest-controllers.md new file mode 100644 index 0000000000..4cd5e820d8 --- /dev/null +++ b/docs/guide-pt-BR/rest-controllers.md @@ -0,0 +1,129 @@ +Controllers (Controladores) +=========== + +Depois de criar as classes de recursos e especificar como os dados de recursos devem ser formatados, a próxima coisa a fazer é criar ações do controller para expor os recursos para os usuários finais através das APIs RESTful. + +Yii fornece duas classes básicas de controller para simplificar seu trabalho de criar ações RESTful: [[yii\rest\Controller]] e [[yii\rest\ActiveController]]. A diferença entre os dois controllers é que o último fornece um conjunto padrão de ações que são especificamente concebidos para lidar com recursos do [Active Record](db-active-record.md). Então, se você estiver usando [Active Record](db-active-record.md) e está confortável com as ações fornecidas, você pode considerar estender suas classes de controller de [[yii\rest\ActiveController]], que permitirá a você criar poderosas APIs RESTful com um mínimo de código. + +Ambos [[yii\rest\Controller]] e [[yii\rest\ActiveController]] fornecem os seguintes recursos, algumas das quais serão descritas em detalhes nas próximas seções: + +* Validação de Método HTTP; +* [Negociação de conteúdo e formatação de dados](rest-response-formatting.md); +* [Autenticação](rest-authentication.md); +* [limitação de taxa](rest-rate-limiting.md). + +[[yii\rest\ActiveController]] oferece também os seguintes recursos: + +* Um conjunto de ações comumente necessárias: `index`, `view`, `create`, `update`, `delete`, `options`; +* Autorização do usuário em relação à ação solicitada e recursos. + + +## Criando Classes Controller + +Ao criar uma nova classe de controller, uma convenção em nomear a classe é usar o nome do tipo de recurso no singular. Por exemplo, para disponibilizar as informações do usuário, o controlador pode ser nomeado como `UserController`. Criar uma nova ação é semelhante à criação de uma ação de uma aplicação Web. A única diferença é que em vez de renderizar o resultado usando uma view e chamando o método `render()`, para ações RESTful você retorna diretamente os dados. O [[yii\rest\Controller::serializer|serializer]] e o [[yii\web\Response|response object]] vão converter os dados originais para o formato solicitado. Por exemplo, + +```php +public function actionView($id) +{ + return User::findOne($id); +} +``` + + +## Filtros + +A maioria dos recursos da API RESTful fornecidos por [[yii\rest\Controller]] são implementadas nos termos de [filters](structure-filters.md). +Em particular, os seguintes filtros serão executados na ordem em que estão listados: + +* [[yii\filters\ContentNegotiator|contentNegotiator]]: suporta a negociação de conteúdo, a ser explicado na seção [Formatação de Resposta](rest-response-formatting.md); +* [[yii\filters\VerbFilter|verbFilter]]: suporta validação de métodos HTTP; +* [[yii\filters\AuthMethod|authenticator]]: suporta autenticação de usuários, que será explicado na seção [Autenticação](rest-authentication.md); +* [[yii\filters\RateLimiter|rateLimiter]]: suporta limitação de taxa, que será explicado na seção + [Limitação de taxa](rest-rate-limiting.md). + +Estes filtros são declarados no método [[yii\rest\Controller::behaviors()|behaviors()]]. +Você pode sobrescrever esse método para configurar alguns filtros, desativar outros, ou adicionar seus próprios filtros. Por exemplo, se você precisar somente de autenticação básica de HTTP, pode-se utilizar o seguinte código: + +```php +use yii\filters\auth\HttpBasicAuth; + +public function behaviors() +{ + $behaviors = parent::behaviors(); + $behaviors['authenticator'] = [ + 'class' => HttpBasicAuth::className(), + ]; + return $behaviors; +} +``` + + +## Estendendo `ActiveController` + +Se a sua classe controller estende de [[yii\rest\ActiveController]], você deve configurar a propriedade [[yii\rest\ActiveController::modelClass||modelClass]] para ser o nome da classe de recurso que você pretende servir através deste controller. A classe deve estender de [[yii\db\ActiveRecord]]. + + +### Customizando Ações + +Por padrão, [[yii\rest\ActiveController]] fornece as seguintes ações: + +* [[yii\rest\IndexAction|index]]: recursos de lista página por página; +* [[yii\rest\ViewAction|view]]: retorna os detalhes de um recurso especificado; +* [[yii\rest\CreateAction|create]]: cria um novo recurso; +* [[yii\rest\UpdateAction|update]]: atualiza um recurso existente; +* [[yii\rest\DeleteAction|delete]]: excluir o recurso especificado; +* [[yii\rest\OptionsAction|options]]: retorna os métodos HTTP suportados. + +Todas essas ações são declarados através do método [[yii\rest\ActiveController::actions()|actions()]]. Você pode configurar essas ações ou desativar alguns delas, sobrescrevendo o método `actions()`, como mostrado abaixo, + +```php +public function actions() +{ + $actions = parent::actions(); + + // desabilita as ações "delete" e "create" + unset($actions['delete'], $actions['create']); + + // customiza a preparação do data provider com o método "prepareDataProvider()" + $actions['index']['prepareDataProvider'] = [$this, 'prepareDataProvider']; + + return $actions; +} + +public function prepareDataProvider() +{ + // preparar e retornar um data provider para a ação "index" +} +``` + +Por favor, consulte as referências de classe para classes de ação individual para saber as opções de configuração que estão disponíveis. + + +### Executando Verificação de Acesso + +Ao disponibilizar recursos por meio de APIs RESTful, muitas vezes você precisa verificar se o usuário atual tem permissão para acessar e manipular o(s) recurso(s) solicitado(s). Com [[yii\rest\ActiveController]], isso pode ser feito sobrescrevendo o método [[yii\rest\ActiveController::checkAccess()|checkAccess()]] conforme abaixo, + +```php +/** +* verifica os privilégios do usuário corrente. +* +* Este método deve ser sobrescrito para verificar se o usuário atual tem o privilégio +* para executar a ação especificada diante do modelo de dados especificado. +* se o usuário não tiver acesso, uma [[ForbiddenHttpException]] deve ser lançada. +* +* @param string $action the ID of the action to be executed +* @param \yii\base\Model $model o model a ser acessado. Se null, isso significa que nenhum model específico está sendo acessado. +* @param array $params additional parameters +* @throws ForbiddenHttpException if the user does not have access +*/ +public function checkAccess($action, $model = null, $params = []) +{ + // verifica se o usuário pode acessar $action and $model + // lança a ForbiddenHttpException se o acesso for negado +} +``` + +O método `checkAccess()` será chamado pelas ações padrões do [[yii\rest\ActiveController]]. Se você criar novas ações e também deseja executar verificação de acesso, você deve chamar esse método explicitamente nas novas ações. + +> Dica: Você pode implementar `checkAccess()` usando o [Role-Based Access Control (RBAC) component](security-authorization.md). +