Ryzom API: Unterschied zwischen den Versionen

Aus EnzyklopAtys

Wechseln zu: Navigation, Suche
(→‎Guild)
(→‎Gilde)
Zeile 45: Zeile 45:
 
{{/Gilden}}
 
{{/Gilden}}
  
−
==[[Ryzom API/Gilde|Gilde]]==
+
== [[Ryzom API/Gilde|Gilde]] ==
 
{{/Gilde}}
 
{{/Gilde}}
  

Version vom 27. Mai 2023, 12:22 Uhr


Important.png
Under Construction Panel.png !!!! WIP !!!! Under Construction Panel.png
Es sind gerade 26 Artikel in der Bearbeitung in der Kategorie "WIP"
Dieser Artikel wird gerade bearbeitet. Bitte laß es den Autor beenden, bevor du es veränderst.
Die letzte Bearbeitung war von Leda am 27.05.2023.
Dieser Artikel wird gerade bearbeitet. Bitte laß es den Autor beenden, bevor du es veränderst. Die letzte Bearbeitung war von Leda am 24.05.2022.
de:Ryzom API• en:Ryzom API• es:Ryzom API• fr:Ryzom API ru:Ryzom API
 
UnderConstruction.png
Übersetzung zur Überprüfung
Gib nicht den Mitwirkenden die Schuld, sondern komm und hilf ihnen. 😎




Diese Seite ist die Ryzom Forge-Version der api.ryzom.com-Seite.

Laut Wikipedia ist eine API oder "Anwendungsprogrammierschnittstelle" eine Computerschnittstelle, die Interaktionen zwischen mehreren Softwarevermittlern definiert. Sie definiert die Arten von Aufrufen oder Anfragen, die gemacht werden können, wie sie gemacht werden können, die Datenformate, die verwendet werden sollten, die zu befolgenden Konventionen, usw. [...]Durch das Verstecken von Informationen ermöglichen APIs eine modulare Programmierung, die es den Benutzern ermöglicht, die Schnittstelle unabhängig von der Implementierung zu nutzen.

In unserem Fall ist Ryzom API ein URL-basiertes System, um einige Ryzom in-game Informationen wie Spielzeit, Charakter, Gildenprofil... zu erhalten. Das API-Änderungsprotokoll kann gefunden werden unter forum.

Grundlagen

Basis-URL

Alle Anfragen verwenden https://api.ryzom.com als Basis-URL.

API Schlüssel

  • API-Schlüssel bestehen aus 41 alphanumerischen Zeichen. Charakterschlüssel beginnen mit 'c' und Gildenschlüssel mit 'g'.
  • API-Schlüssel müssen mit "RyzomAPI app" erstellt werden: https://app.ryzom.com/app_ryzomapi
  • Sie müssen Gildenleiter oder hoher Offizier sein, um den Api-Schlüssel der Gilde zu verwalten und einzusehen.

PHP API

Die PHP-API-Bibliothek befindet sich im ryzom API client-Repository.

Bibliotheken von Drittanbietern

(PHP) Übersetzungen der Blätter und Informationen über Ressourcen finden Sie in der https://github.com/nimetu/ryzom_extra Repository. Der json-resources Zweig hat Daten im Format JSON.

Python-Interface ?

Funktionen

Zeit

Um die Uhrzeit und das Datum in Ryzom zu erfahren.

Verwendung

<base URL>/time.php

URL-Parameter

Format
(optional), Standardwerte roh.
  • raw : Gibt den Tick zurück. Der Tick des Servers ist eine 32-Bit-Ganzzahl, die alle 100 Millisekunden um eins erhöht wird.
  • txt : Gibt eine für Homin lesbare Zeichenkette zurück.
  • xml : Gibt eine xml-Datei zurück, die alle Shard-Zeitinformationen enthält.

Cache-Dauer

Die Daten werden für 1 Minute zwischengespeichert.

XML structure

<shard_time>
  <server_tick>514105152</server_tick>
  <jena_year>2576</jena_year>
  <day_of_jy>319</day_of_jy>
  <month_of_jy>10</month_of_jy>
  <cycle>0</cycle>
  <day_of_cycle>319</day_of_cycle>
  <month_of_cycle>10</month_of_cycle>
  <day_of_month>19</day_of_month>
  <day_of_week>1</day_of_week>
  <season>3</season>
  <day_of_season>49</day_of_season>
  <time_of_day>13</time_of_day>
  <txt_en>13h - Dua, Mystia 20, 1st AC 2576</txt_en>
  <txt_fr>13h - Dua, Mystia 20, 1er CA 2576</txt_fr>
  <txt_de>13h - Dua, Mystia 20, 1. AZ 2576</txt_de>
  <cache created="1387437183" expire="1387437243"/>
</shard_time>

PHP-Interface

ryzom_time_api() : Gibt SimpleXMLElement oder boolesches false bei Fehlschlag zurück.
<?php
  require_once "ryzomapi_lite.php";

  $time = ryzom_time_api('xml');
  if ($time !== false) {
    $txt_en = htmlspecialchars($time->txt_en);
    echo "Atys time is {$txt_en}";
  } else {
    echo "API failure";
  }
?>


Charakter

Zugang zu Charakterinformationen.

Verwendung

<base URL>/character.php?apikey=key
<base URL>/character.php?apikey[=key1&apikey[]=key2

URL-Parameter

apikey
Charakter-API-Schlüssel beginnt mit 'c'

Cache-Laufzeit

<character> xml-Element hat die Attribute *created* und *cached_until* (utc-Zeitstempel)

XML-Struktur

API ist in der Lage, Informationen über mehrere Charaktere auf einmal zurückzugeben, und daher ist jedes <character>-Element ein Kind des <ryzomapi>-Wurzelelements: 

<ryzomapi>
  <character apikey="key1" created="1387369332" modules="C01:P01" cached_until="1387369632">
    ....
  </character>
  <character apikey="key2" created="1387369332" modules="P01" cached_until="1387369632">
    ....
  </character>
</ryzomapi>

Fehler bei ungültigem Schlüssel: 

<character apikey="key1" created="1387369873">
  <error code="404">Ungültiger Schlüssel</error>
</character>

Mögliche Fehlercodes sind auf API-Fehlercodes aufgelistet.

PHP-Interface

ryzom_character_api($apikey)
$apikey kann entweder ein String (einzelner Schlüssel) oder ein Array von Strings sein.

Bei Erfolg gibt die Funktion ein assoziatives Array von SimpleXMLElement mit apikey als Array-Index zurück. Bei einem Fehler gibt die Funktion den booleschen Wert false zurück. 

<?php
require_once "ryzomapi_lite.php";

function info($char) {
  if (isset($char->error)) {
    $apikey = htmlspecialchars($char['apikey']);
    $error = htmlspecialchars($char->error);
    $code = (int)$char->error['code'];
    echo "Character API key '{$apikey}' failed: {$code}:{$error}";
  } else {
    $name = htmlspecialchars($char->name);
    echo "Character name: {$name}";
  }
}

$apikey = 'cABCDEF';
$chars = ryzom_character_api($apikey);
if ($chars !== false) {
  info($chars[$apikey]);
} else {
  echo "Character API failed";
}

$apikeys = ['cABCDEF', 'c123456'];
$chars = ryzom_character_api($apikeys);
if ($chars !== false) {
  foreach($chars as $char) {
    info($char);
  }
} else {
  echo "Charakter-API gescheitert";
}


Gilden

Zeigt die Liste aller Gilden an.

Verwendung

<base URL>/guilds.php

Cache-Laufzeit

Das zurückgegebene XML enthält das Element <cache> mit den Attributen created und expire (utc timestamp)

XML-Struktur

<guilds>
  <cache created="1387371064" expire="1387374664"/>
  <shard>atys</shard>
  <guild>
    <gid>105906182</gid>
    <name>Atrium</name>
    <race>Fyros</race>
    <icon>575080624687965565</icon>
    <creation_date>131736955</creation_date>
    <description>Hier bist du der Hüter, dein Schicksal ist es, die Regeln zu machen, die eingehalten werden müssen.</description>
  </guild>
  <guild>
    ....
  </guild>
</guilds>

PHP-Interface

ryzom_guildlist_api()

Die Funktion gibt bei Erfolg ein SimpleXMLElement-Objekt oder bei einem Fehler ein boolesches false zurück. 

<?php
  require_once "ryzomapi_lite.php";

  $guilds = ryzom_guildlist_api();
  if ($guilds !== false) {
    echo '<pre>';
    foreach($guilds->guild as $guild) {
      $gid = (int)$guild->gid;
      $name = htmlspecialchars($guild->name);
      echo "{$gid} {$name}\n";
    }
    echo '</pre>';
  } else {
    echo "API failure";


Gilde

Zugang zu Gilden-Informationen.

Verwendung

<base URL>/guild.php?apikey=key
<base URL>/guild.php?apikey[]=key1&apikey[]=key2

URL-Parameter

apikey 
Gilden-API-Schlüssel beginnt mit 'g'

Cache-Laufzeit

Das Guild-Xml-Element hat die Attribute created und cached_until (utc timestamp)

XML-Struktur

Die API ist in der Lage, Informationen für mehrere Gilden gleichzeitig zu liefern, und daher ist jedes <Gilde>-Element ein Kind von <ryzomapi>-Wurzelelementen. 

<ryzomapi>
  <guild apikey="key1" created"1387369332" modules="G01:G02:G03:G04:P01" cached_until="1387369632">
    ...
  </guild>
  <guild apikey="key2" created"1387369332" modules="P01" cached_until="1387369632">
    ...
  </guild>
</ryzomapi>

Fehler bei ungültigem Schlüssel: 

<guild apikey="key1" created="1387369873">
  <error code="404">ungültiger Schlüssel</error>
</guild>

Mögliche Fehlercodes sind auf API-Fehlercodes aufgelistet.

PHP-Interface

ryzom_guild_api($apikey)

$apikey kann entweder ein String oder ein Array von Strings sein

Funktion gibt assoziatives Array von SimpleXMLElement mit $apikey als Array-Index zurück Bei Fehlschlag gibt die Funktion den booleschen Wert false zurück 

<?php
require_once "ryzomapi_lite.php";

function info($guild) {
  if (isset($guild->error)) {
    $apikey = htmlspecialchars($guild['apikey']);
    $error = htmlspecialchars($guild->error);
    $code = (int)$guild->error['code'];
    echo "Gilden-API-Schlüssel '{$apikey}' gescheitert: {$code}:{$error}";
  } else {
    $name = htmlspecialchars($guild->name);
    echo "Gilden-Name: {$name}";
  }
}

$apikey = 'gABCDEF';
$guilds = ryzom_guild_api($apikey);
if ($guilds !== false) {
  info($guilds[$apikey]);
} else {
  echo "Gilden-API gescheitert";
}

$apikeys = ['gABCDEF', 'g123456'];
$guilds = ryzom_guild_api($apikeys);
if ($guilds !== false) {
  foreach($guilds as $guild) {
    info($guild);
  }
} else {
  echo "Gilden-API gescheitert";
}


API-Fehlercodes

404 ungültiger API-Schlüssel 
Kein solcher API-Schlüssel.
403 key expired 
API-Schlüssel ist gültig, aber abgelaufen
503 Charakterdaten sind nicht initialisiert
503 Gilden-Daten sind nicht initialisiert
Temporärer serverseitiger Fehler, der anzeigt, dass die Charakter-/Gildeninformationen derzeit nicht verfügbar sind.
Daten werden verfügbar sein, nachdem sich der Charakter im Spiel eingeloggt hat

Tools

Render

Dies ist ein Satz von PHP-Funktionen zum Rendern einer Webseite im Ryzom-Stil.

CSS-Datei

Sie müssen die Ryzom-css-Datei manuell einbinden: 

<link href="https://api.ryzom.com/data/css/ryzom_ui.css" rel="stylesheet" media="all">

PHP-Interface

ryzom_render_window($title, $content, array $links)

Gibt HTML-Markup zurück, das dem Stil des Ingame-Fensters ähnelt

$title
$content
$links - (optional) assoziatives Array, das die Schaltflächen auf der rechten Seite der Titelleiste des Fensters definiert
<?php
require_once "ryzomapi_lite.php";

$links = array(
  array('href' => 'http://www.ryzom.com/', 'text' => 'Ryzom-Webseite'),
  array('href' => 'http://app.ryzom.com/app_ryzomapi/', 'text' => 'RyzomAPI-App'),
);

echo ryzom_render_window('Title', 'Hallo Welt!', $links);


Guild icon

Ryzom API/Guild icon

Item icon

Ryzom API/Item icon

In Game

AppZone

Benutzerauthentifizierung für in AppZone registrierte Anwendungen

Verwendung

URL-Werte
user -- base64 kodiertes php serialisiertes Array
checksum -- sha1 hash_hmac mit geheimem App-Schlüssel aus AppZone

Aufgrund von php serialize muss die Prüfsumme validiert werden, bevor der Benutzerwert sicher verwendet werden kann.
Eine validierende Prüfsumme bietet auch eine starke Garantie dafür, daß der Benutzer derjenige ist, der er vorgibt zu sein.

Beispiel, wie die Rückmeldung erstellt wird: 

$userArray = [
  'timestamp' => "0.9696200 1503915319",
  'app_url' => 'http://...',
  'id' => "1",
  'char_name' => 'Spieler',
  'race' => 'Tryker',
  'cult' => 'Neutral',
  'civ' => 'Neutral',
  'organization' => 'Marodeur',
  'guild_id' => '105906000',
  'guild_icon' => '17',
  'guild_name' => 'Gilde',
  'grade' => 'Anführer',
  'lang' => 'de'
];

$user = base64_encode(serialize($userArray));
$checksum = hash_hmac('sha1', $user, $appKey);

timestamp enthält Mikrosekunden und Sekunden, in denen die Antwort erstellt wurde, und sollte überprüft werden, um zu verhindern, dass dieselbe Antwort mehrfach wiedergegeben wird.
app_url muss aktiviert werden, um zu verhindern, dass dieselbe AppZone-Antwort in anderen Anwendungen verwendet wird.

PHP-Interface

ryzom_app_authenticate(&$user)

Diese Funktion überprüft die AppZone-Benutzer- und -Prüfsummen-URL-Parameter. Verwendet $_GET['user'] und $_GET['checksum'] direkt.
Die Funktion gibt bei Erfolg den booleschen Wert true zurück. Die Variable $user enthält Informationen von AppZone oder eine Fehlermeldung, wenn ein Fehler aufgetreten ist. 

$_SESSION['app.user']
ist für künftige Anfragen gesetzt. PHP-Sitzung ist erforderlich.

Konstanten welche definiert sein sollten :
RYAPI_AUTH_KEY
geheimer Schlüssel in der AppZone
wenn leer, dann werden die Benutzerdaten nicht überprüft (nicht empfohlen)
RYAPI_APP_URL
App-Url in der AppZone
wenn leer, dann wird automatisch die am besten ermittelte Url verwendet
wenn false, dann wird die Anwendungs-Url nicht verifiziert
RYAPI_APP_MAXAGE
Höchstalter in Sekunden für die Gültigkeit der AppZone-Url
wenn 0, wird der Zeitstempel (timestamp) nicht verifiziert 
<?php
  require_once "ryzomapi_lite.php";

  define('RYAPI_AUTH_KEY', 'secret-key');
  define('RYAPI_APP_URL', 'http://app.url/');
  define('RYAPI_APP_MAXAGE', 30);

  session_start();

  $user = false;
  if (ryzom_app_authenticate($user)) {
    $charName = htmlspecialchars($user['char_name']);
    echo "Hallo {$charName}!";
  } else {
    $error = htmlspecialchars($user);
    echo "Autentifizierungs-Fehler ({$error}).";
  }


In-game browser

WikipAtys

Wiki implemetation

Pages in Category : "API templates" :

Extension:DynamicPageList (DPL), version 3.1.1: Warnung: Kein passender Eintrag gefunden!

⚠Warning
The code required to retrieve icons is raw html. You won't be able to format pictures as "easily" as when you use wiki code and the image is stored on Atys commons.

Examples

Links




Ergänzungen zu dieser Seite:

Neueste Version 27.05.2023•ᐒ
Abgerufen von „https://de.wiki.ryzom.com/w/index.php?title=Ryzom_API&oldid=35020“