Fala galera, finalmente vou trazer um post que une duas coisas que amo fazer nessa vida: jogar World of Warcraft e programar. Faz tempo que queria testar a API de consultas 
disponibilizadas pela Blizzard, a ideia é poder criar aplicativos onde o usuário loga com sua conta do Battle.net e consegue visualizar coisas bacanas como seus personagens e atributos(nome, reino, guilda, raça, última modificação, classe, gênero, papel,…), isso é bem legal e abre a possibilidade da comunidade de World of Warcraft usar a criatividade e fazer todo tipo de app. Vamos nessa?
Vou descrever em formato de passo-a-passo listando os tópicos abaixo e dentro de cada um descrevo com mais detalhes:
Criar uma conta na dev.battle.net
- Ao entrar no site verá um botão azul grande escrito “Create a Mashery Account“, clique nele. Mashery é parceira da Blizzard e provê toda a infraestrutura necessária para habilitar as consultas de dados.
- Será mostrada a tela com o formulário onde deve colocar seus dados: email, usuário e senha.
Formulário de cadastro do dev.battle.net
Feito isso seu cadastro será efetuado e receberá um email para confirmar a conta.
Acessar o portal e gerar uma chave para seu app
Agora que já possui uma conta deve acessar com seu usuário e senha o site https://dev.battle.net e automaticamente será direcionado para uma tela para registrar uma aplicação(app ou site) que fará as consultas. Este procedimento irá gerar uma chave(API Key) que permitirá fazer as requisições. Ele é bem grandinho mas não se assuste, as informações são simples.
- Informe um nome qualquer. Ex: minha_app
- Informe um site: Ex: dicaswarcraft.com.br
- A descrição do que vai fazer é opcional.
- URL de callback também é opcional, como só vamos consultar não precisaremos por enquanto. Lá na frente será legal sermos automaticamente notificados de mudanças no serviço.
- O outros campos deixa do jeito que tá.
A informação de “BASIC PLAN” é porque nesse plano de uso existe um limite de chamadas de 100 por segundo, que já é uma quantidade boa para começarmos. Aplicações maiores com certeza usam muito mais que isso.
Acessando as consultas usando a chave gerada
Feito o passo acima é apresentada a sua chave na tela https://dev.battle.net/apps/mykeys. Coloquei os “*” abaixo para não mostrar minha chave obviamente, não compartilhe a de vocês com ninguém, a ideia é que utilizando a autenticação OAuth cada usuário faça um acesso seguro a sua app, se autentique com a Battle.net e puxe os dados dele, em momento algum o usuário verá a key da aplicação.
- Application: DicasWarcraft
- Key: ****************************
- Secret: **************************
- Status: active
- Created: 2 hours ago
Bom e agora? Agora vem a parte legal, já temos a chave então vamos acessar a página da documentação que mostra como fazermos nossa primeira consulta, sem precisar escrever nem uma linha de código. Acesse o endereço https://dev.battle.net/io-docs.
- Logo quando entramos na tela “API Docs” nos deparamos com uma lista enorme de bases de dados de onde podemos consultar informações. De acordo com o guia existem 3 API’s da comunidade para Starcraft II, World of Warcraft e Diablo III, ainda não entendi nem olhei cada uma delas então fica para um post futuro, vamos começar com a “Community OAuth Profile API”.
-
Lista de comunidades disponíveis
- Algo a se observar são as repetições, temos vários SC2(Starcraft), WoW Communit Auth, D3(Diablo) entre outros. Isto ocorre porque existe uma divisão por regiões e por jogos, os dados disponibilizados pela API são limitados pela região em que se encontram, como por exemplo, EU (Europa), US (Estados Unidos) e KR (Coréia). Isto também vale para as URL’s de consulta, veja o quadro abaixo:
| Region | Host | Available Locales |
|---|---|---|
| US | https://us.api.battle.net/ | en_US es_MX pt_BR |
| Europe | https://eu.api.battle.net/ | en_GB es_ES fr_FR ru_RU de_DE pt_PT it_IT |
| Korea | https://kr.api.battle.net/ | ko_KR |
| Taiwan | https://tw.api.battle.net/ | zh_TW |
| China | https://api.battlenet.com.cn/ | zh_CN |
| South East Asia* | https://sea.api.battle.net/ | en_US |
Toda a autenticação OAuth é feita através da Mashery que gerencia as requisições para a API. Vamos finalmente fazer a requisição para os dados da sua conta do Battle.net? Abaixo a imagem mostra os campos que vamos preencher para fazer a autenticação:
O primeiro campo “Client ID” é a chave que geramos nas etapas anteriores, o “Client Secret” também foi gerado lá em cima junto com a chave. Agora clique em “Authorize”. Será aberta uma tela para você fazer a autenticação com o Battle.net com suas credencias, as mesma usadas para logar na aplicação que usamos para jogar WoW e outros jogos da Blizzard.
Feito o login corretamente, o “Authorization Code” é exibido abaixo e um botão “Get Access Token”, vamos clicar nele para gerar nosso “Access Token”. Cumpridas estas etapas já podemos fazer a requisição. Neste caso temos 3 métodos que podemos chamar para consultar os dados:
- USER/ACCOUNT/USER
- SC2 OAUTH PROFILE/SC2/PROFILE/USER
- WOW OAUTH PROFILE/WOW/USER/CHARACTERS
Como estamos falando do WoW vamos usar o terceiro método que retorna dados dos personagens da conta em World of Warcraft. Basta clicar em “Try it!” Veja o resultado:
{ "characters": [{ "name": "Darkkiskex", "realm": "Goldrinn", "battlegroup": "Rampage", "class": 1, "race": 10, "gender": 0, "level": 62, "achievementPoints": 480, "thumbnail": "goldrinn/31/156045855-avatar.jpg", "spec": { "name": "Fury", "role": "DPS", "backgroundImage": "bg-warrior-fury", "icon": "ability_warrior_innerrage", "description": "A furious berserker wielding a weapon in each hand, unleashing a flurry of attacks to carve her opponents to pieces.", "order": 1 }, "lastModified": 1486151079000 }, { "name": "Helldjin", "realm": "Goldrinn", "battlegroup": "Rampage", "class": 8, "race": 11, "gender": 0, "level": 9, "achievementPoints": 0, "thumbnail": "goldrinn/60/156507196-avatar.jpg", "lastModified": 0 }, { "name": "Wuchang", "realm": "Gallywix", "battlegroup": "Ruin", "class": 7, "race": 25, "gender": 0, "level": 57, "achievementPoints": 305, "thumbnail": "gallywix/128/177235328-avatar.jpg", "spec": { "name": "Elemental", "role": "DPS", "backgroundImage": "bg-shaman-elemental", "icon": "spell_nature_lightning", "description": "A spellcaster who harnesses the destructive forces of nature and the elements.", "order": 0 }, "guild": "Heróis de Valhala", "guildRealm": "Gallywix", "lastModified": 1486090941000 }, { "name": "Kyhaven", "realm": "Quel'Thalas", "battlegroup": "Vindication", "class": 2, "race": 1, "gender": 0, "level": 1, "achievementPoints": 0, "thumbnail": "quelthalas/189/87999165-avatar.jpg", "lastModified": 0 }, { "name": "Feriuslaycan", "realm": "Goldrinn", "battlegroup": "Rampage", "class": 11, "race": 22, "gender": 0, "level": 5, "achievementPoints": 0, "thumbnail": "goldrinn/239/156459247-avatar.jpg", "lastModified": 0 }, { "name": "Dominusbull", "realm": "Goldrinn", "battlegroup": "Rampage", "class": 3, "race": 6, "gender": 0, "level": 5, "achievementPoints": 0, "thumbnail": "goldrinn/150/156718998-avatar.jpg", "lastModified": 0 }] }
Obs: caso apareça um erro com código 403 (Forbidden) no retorno, significa que você não efetuou uma das etapas acima relacionadas a chave, certifique-se de ter clicado em “Get Access Token”.
E ai, bacana né? Para quem não conhece o formato dos dados retornados é chamado de JSON(Javascript Object Notation), um tipo de notação do tipo chave/valor muito utilizado em chamadas deste tipo por ser muito leve, perfeito para dispositivos móveis por exemplo mas muito usado em sites também.
Tem muito o que falar sobre tudo isso, mas o post já esta gigante e em breve trago mais novidades, da próxima vamos ver quais outros dados podemos trazer e talvez criar algo bacana para disponibilizar para a comunidade do jogo. Este post tem como origem no meu outro blog que é meu diário de bordo do jogo em DicasWarcraft.
Até a próxima galera.
Rodrigo R. Ferreira 