Full Circle Magazine FR

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
**I had wanted to present you with an example of creating your own API wrapper library, but the site that I was going to use has moved to a paid model. However, I have found a different site that does basically the same thing at no cost to you, so I’ll start.

The Movie Database (themoviedb.org) is a great place to find out information about your favorite movies and TV shows, as well as the people who star and help create them. The first thing to do is create an account on the main system and then you can sign up for an API key. Once you have a key, you can query the database through a simple Python program using the wrapper that I’ve created and am presenting here. The API wrapper library covers only a few of the various calls that can be made to the system, mainly the ones that were immediately useful to me and probably to you.**

Je voulais vous présenter un exemple de création de votre propre bibliothèque d'enpaqueteurs (en anglais, wrapper) d'API, mais le site que je comptais utiliser est passé à un modèle payant. Cependant, j'ai trouvé un autre site qui fait pratiquement la même chose sans frais pour vous, alors je vais commencer.

The Movie Database (themoviedb.org) est un site formidable pour trouver des informations sur vos films et émissions de télévision préférés, ainsi que sur les personnes qui les interprètent et contribuent à les créer. La première chose à faire est de créer un compte sur le système principal, puis de demander une clé API. Une fois que vous avez une clé, vous pouvez interroger la base de données à l'aide d'un simple programme Python utilisant le wrapper que j'ai créé et que je présente ici. La bibliothèque du wrapper API ne couvre que quelques-uns des différents appels qui peuvent être faits au système, principalement ceux qui m'ont été immédiatement utiles, probablement aussi à vous.


**Once you have your key, you should look at the different API calls that can be made and what those calls will return to you. The documentation is at https://developers.themoviedb.org/3/getting-started/introduction, and covers only the version 3 API calls. Most of us will find the Movie information very handy so we’ll look at it first.

Any query for information on a movie or TV show starts with obtaining the ID number of the show you want to investigate. However, in order to obtain the ID, you must first do a search. We must format a URL which includes our API key and the name of the movie. Here is a dummy URL that you can use as an example.

https://api.themoviedb.org/3/search/movie?api_key=<<api_key>>&language=en-US&query=(MovieName)&page=1&include_adult=false**

Une fois que vous avez votre clé, vous devez examiner les différents appels d'API qui peuvent être effectués et ce que ces appels vous retourneront. La documentation se trouve à l'adresse https://developers.themoviedb.org/3/getting-started/introduction et ne couvre que les appels API de la version 3. La plupart d'entre nous trouveront très pratiques les informations sur les films ; c'est pourquoi nous allons commencer par les examiner.

Toute requête d'informations sur un film ou une émission de télévision commence par l'obtention du numéro d'identification de l'émission sur laquelle vous souhaitez enquêter. Toutefois, pour obtenir ce numéro, vous devez d'abord effectuer une recherche. Nous devons formater une URL qui comprend notre clé API et le nom du film. Voici une URL fictive que vous pouvez utiliser comme exemple.

https://api.themoviedb.org/3/search/movie?api_key=<<api_key>>&language=en-US&query=(MovieName)&page=1&include_adult=false


**To break it down, it would be…
•  Base UR: https://api.themoviedb.org/
•  API Version: 3/
•  Command: search/
•  Type:          movie?
•  API Key:     <Your Key Here> &
•  Language:  en-US&
•  Query:        (Movie Name)&
•  Page #:      1&
•  Include Adult FIlms: false

There are also two other fields you can use to refine your search, year and primary_release_year.

Let’s say we want to search for the Ant Man movie. Using the above format, the URL would look like this (without the API key):

https://api.themoviedb.org/3/search/movie?api_key=<Your Key Here >&language=en-US&query=Ant%20Man&page=1&include_adult=false&region=US**

En la décomposant, ça donnerait...
- Base UR : https://api.themoviedb.org/
- Version de l'API : 3/
- Commande : search/
- Type : movie ?
- Clé API :     <Votre clé ici> &
- Langue : en-US&
- Requête :        (Nom du film)&
- Page # : 1&
- Inclure les films pour adultes : false

Il existe également deux autres champs que vous pouvez utiliser pour affiner votre recherche : year et primary_release_year.

Disons que nous voulons rechercher le film Ant Man. En utilisant le format ci-dessus, l'URL ressemblerait à ceci (sans la clé API) :

https://api.themoviedb.org/3/search/movie?api_key=<Votre clé ici>&language=en-US&query=Ant%20Man&page=1&include_adult=false&region=US


**The information that comes back will be in JSON format.  (Ronnie had a problem with the JSON response, trying to get it to fit nicely in the magazine.  So, to see the full response, check the readme at my repository https://github.com/gregwa1953/FCM178 )

Inside the JSON response you will find a field named id as well as fields for original title, overview and so on that will help you decide which of the results contain the ID that you are looking for.

id: 102899,
original_language: "en",
original_title: "Ant-Man",
overview: "Armed with the astonishing ability to shrink in scale but increase in strength, master thief Scott Lang must embrace his inner-hero and help his mentor, Doctor Hank Pym, protect the secret behind his spectacular Ant-Man suit from a new generation of towering threats. Against seemingly insurmountable obstacles, Pym and Lang must plan and pull off a heist that will save the world.",

That gives a fair amount of data about the movie. If that isn’t enough, you can go for the Movie Detail:
https://api.themoviedb.org/3/movie/{102899}?api_key=<<api_key>>&language=en-US**

Les informations retournées seront au format JSON.  (Ronnie a eu un problème avec la réponse JSON, en essayant de la faire tenir correctement dans le magazine.  Aussi, pour voir la réponse complète, consultez le fichier readme sur mon dépôt https://github.com/gregwa1953/FCM178).

Dans la réponse JSON, vous trouverez un champ nommé id ainsi que des champs avec le titre original, l'aperçu, etc. qui vous aideront à décider quels résultats contiennent l'ID que vous recherchez.

id : 102899,
original_language : "en",
original_title : "Ant-Man",
overview: (aperçu) : (traduction) « Armé de l'étonnante capacité de rétrécir en taille mais d'augmenter en force, le maître voleur Scott Lang doit embrasser le héros qui est en lui et aider son mentor, le docteur Hank Pym, à protéger le secret derrière son spectaculaire costume Ant-Man contre une nouvelle génération de menaces gigantesques. Face à des obstacles apparemment insurmontables, Pym et Lang doivent planifier et réaliser un vol qui sauvera le monde. »

Cela donne une bonne quantité d'informations sur le film. Si cela ne suffit pas, vous pouvez consulter les détails du film :
https://api.themoviedb.org/3/movie/{102899}?api_key=<<Votre clé ici>>&language=en-US


**Again, the data comes back in JSON format.  (Again, the actual JSON response is shown on my github repository.)

id: 102899,
imdb_id: "tt0478970",
original_language: "en",
original_title: "Ant-Man",
overview: "Armed with the astonishing ability to shrink in scale but increase in strength, master thief Scott Lang must embrace his inner-hero and help his mentor, Doctor Hank Pym, protect the secret behind his spectacular Ant-Man suit from a new generation of towering threats. Against seemingly insurmountable obstacles, Pym and Lang must plan and pull off a heist that will save the world.",

Television series queries would be similar, but in addition to looking for a specific TV series and its details, you can get season and episode details as well. Going even further, for movies you can get the names of the cast and crew, and the same thing for TV shows plus guest stars for each episode (if available).

While you can simply use your API key and run the queries (all of them) via a web browser, I think that it’s a bit simpler to use Python to make the calls. Hence the API wrapper.**

Là encore, les données sont retournées au format JSON.  (Encore une fois, la réponse JSON réelle est présentée sur mon dépôt github).

id : 102899,
imdb_id : "tt0478970",
original_language : "en",
original_title : "Ant-Man",
aperçu : « Armé de l'étonnante capacité de rétrécir en taille mais d'augmenter en force, le maître voleur Scott Lang doit embrasser le héros qui est en lui et aider son mentor, le docteur Hank Pym, à protéger le secret derrière son spectaculaire costume Ant-Man contre une nouvelle génération de menaces gigantesques. Face à des obstacles apparemment insurmontables, Pym et Lang doivent planifier et réaliser un vol qui sauvera le monde. »

Les recherches de séries télévisées sont similaires, mais en plus de rechercher une série télévisée spécifique et ses détails, vous pouvez également obtenir les détails de la saison et des épisodes. En allant encore plus loin, pour les films, vous pouvez obtenir les noms des acteurs et de l'équipe, et la même chose pour les séries télévisées, plus les « guest stars » pour chaque épisode (si disponible).

Bien que vous puissiez simplement utiliser votre clé API et exécuter les requêtes (toutes) via un navigateur Web, je pense que c'est un peu plus simple d'utiliser Python pour effectuer les appels. D'où le wrapper API.


**So the wrapper is named (imagine how many hours it took me to come up with this name…) wrapper.py. As always, it starts out with a series of imports:

# ======================
# Imports
# ======================
import requests
import json
import pprint
import locale

I included pprint to allow me to look at the data in a nice format when I was doing development and for troubleshooting purposes. The locale library helps to make sure that the language field is formatted correctly for the API query for where you are. 

Just after the import section, I have the following variable definitions which force them to global variables. In order to use the wrapper library, be sure to assign your API key to the mykey3 variable:

mykey3 = <Your API Key Here>

loc = locale.getlocale()[0]**

Le wrapper s'appelle donc (imaginez combien d'heures il m'a fallu pour trouver ce nom...) wrapper.py. Comme toujours, il commence par une série d'importations :

# ======================
# Imports
# ======================
import requests
import json
import pprint
import locale

J'ai inclus pprint pour me permettre d'examiner les données dans un format agréable lorsque je faisais du développement et à des fins de dépannage. La bibliothèque locale permet de s'assurer que le champ de la langue est formaté correctement pour la requête API de l'endroit où vous vous trouvez. 

Juste après la section d'importation, j'ai les définitions de variables suivantes qui les forcent à devenir des variables globales. Afin d'utiliser la bibliothèque wrapper, assurez-vous d'attribuer votre clé API à la variable mykey3 :

mykey3 = <Votre clé API ici>

loc = locale.getlocale()[0]


**The first major function will search the movie database by name, and return the requests’ status code, the number of results, the number of pages, and a list of dictionaries that has been snipped out of the JSON data stream.

At this point, you are probably wondering what is the deal with pages? This is very important, since if there are more than about 20 matches found, the API will break the result set into a set of pages. You will need to make multiple requests using the Search Movie query – asking for each page in order. To keep you (and myself) from having to do this, I handle all the requests for the search within the function, and merge all of the data and only a single list of dictionaries.

So the function to search for a movie using the wrapper would be as shown top right.

I have to say, if you have a chance to stream this movie, please do! You won’t be disappointed.

All of the data that is provided in the JSON file is included, it’s just formatted in an easier format for you to deal with, in the endresults variable (again it’s a list of dictionary objects).

Using pretty print, the returns from the function would look like thaat shown next page, top right.

So the information we REALLY want would be the id, so we can simply extract this by using…

movie_id = endresults[0]["id"]**

La première fonction principale recherchera dans la base de données par nom de film et renverra le code d'état de la requête, le nombre de résultats, le nombre de pages et une liste de dictionnaires extraits du flux de données JSON.

À ce stade, vous vous demandez probablement ce qu'il en est des pages. C'est très important, car s'il y a plus de 20 correspondances trouvées, l'API divisera l'ensemble des résultats en un ensemble de pages. Vous devrez faire plusieurs demandes à l'aide de la requête « Search Movie », en demandant successivement chaque page. Pour vous éviter (et m'éviter) d'avoir à le faire, je traite toutes les demandes de recherche dans la fonction, et je fusionne toutes les données et une seule liste de dictionnaires.

Ainsi, la fonction de recherche d'un film à l'aide du wrapper serait celle présentée en haut à droite.

Je dois dire que si vous avez l'occasion de regarder ce film en streaming, faites-le ! Vous ne serez pas déçu.

Toutes les données fournies dans le fichier JSON sont incluses, elles sont juste formatées dans un format plus facile à gérer, dans la variable endresults (encore une fois, c'est une liste d'objets de dictionnaire).

En utilisant la fonction « pretty print », les retours de la fonction ressembleraient à ce qui est montré sur la page suivante, en haut à droite.

L'information que nous voulons VRAIMENT est l'identifiant, nous pouvons donc simplement l'extraire en utilisant...

movie_id = endresults[0]["id"]


**Then the call to get the movie details would be:

status_code, jdata = wrapper.get_movie_by_id(mykey3, movie_id, loc)

And the returned information is shown bottom right.

The current version supports the following functions from the API version 3.

Currently supported functions:

*** Search functions will return a number of results depending on query ***
      Search_movie, search_tvshow, search_multi

*** Get detail functions (REQUIRE ID FROM SEARCH FUNCTIONS) ***

Get_movie_by_id, get_movie_credits, get_person, get_tvshow_by_id.

Get_tv_season_detail, get_tv_episode_detail, get_tv_show_season_credits,

Get_movie_watch_providers, get_tv_on_air (VERY EXPERIMENTAL)**

L'appel pour obtenir les détails du film serait alors le suivant :

status_code, jdata = wrapper.get_movie_by_id(mykey3, movie_id, loc)

Les informations renvoyées sont affichées en bas à droite.

La version actuelle prend en charge les fonctions suivantes de la version 3 de l'API.

Currently supported functions:

*** Search functions will return a number of results depending on query ***
      Search_movie, search_tvshow, search_multi

*** Get detail functions (REQUIRE ID FROM SEARCH FUNCTIONS) ***

Get_movie_by_id, get_movie_credits, get_person, get_tvshow_by_id.

Get_tv_season_detail, get_tv_episode_detail, get_tv_show_season_credits,

Get_movie_watch_providers, get_tv_on_air (VERY EXPERIMENTAL)


**I’ve decided to go ahead and release this early version (0.4) that you can use as a learning tool.

At the end of the file is a simple test program that you can use by simply calling:

python wrapper.py

If you want to use this in your own programs, just copy it into your project folder and import it into your source code.

As you can see, creating a wrapper for many APIs can be fairly simple. That’s not to say that every API would be this easy, but this should give a good starting point for you to create your own API library wrappers for fun and potentially profit.

I’ve placed the wrapper.py file on my repository at https://github.com/gregwa1953/FCM178**

J'ai décidé d'aller de l'avant et de publier cette première version (0.4) que vous pouvez utiliser comme outil d'apprentissage.

A la fin du fichier se trouve un programme de test simple que vous pouvez utiliser en appelant simplement :

python wrapper.py

Si vous souhaitez l'utiliser dans vos propres programmes, il vous suffit de le copier dans le dossier de votre projet et de l'importer dans votre code source.

Comme vous pouvez le constater, la création d'un wrapper pour de nombreuses API peut être assez simple. Cela ne veut pas dire que toutes les API sont aussi simples, mais cela devrait vous donner un bon point de départ pour créer vos propres wrappers de bibliothèque API pour votre plaisir et potentiellement pour votre profit.

J'ai placé le fichier wrapper.py sur mon dépôt à l'adresse https://github.com/gregwa1953/FCM178.