Suite

API ArcGIS pour JavaScript RouteParameters vs API REST

API ArcGIS pour JavaScript RouteParameters vs API REST


J'ai le service d'analyse de réseau et j'ai besoin d'obtenir l'itinéraire entre deux points, mais je ne veux pas la polyligne à chemin unique, mais plutôt un ensemble de chemins représentant les bords qu'il parcourt (presque une polyligne à chemin unique cassée aux nœuds du réseau ).

J'ai découvert qu'il existe un paramètre appelé "populate_route_edges" (lien ici) qui semble être le seul paramètre qui me permettra d'obtenir ce dont j'ai besoin, mais je ne trouve pas son paramètre correspondant dans l'objet RouteParameters de l'API ArcGIS pour JavaScript.

Est-ce que quelqu'un sait comment obtenir le résultat de l'itinéraire polyligne en plusieurs parties à partir d'une analyse de réseau, où les parties sont les bords (segments) du réseau routier ?


étant donné que le paramètre que vous avez mentionné n'est disponible que via la documentation du service asynchrone à laquelle vous êtes lié, votre meilleur pari serait de l'appeler via une tâche de géoprocesseur générique.

cette approche vous permet un contrôle plus fin à la fois dans la définition du type d'exécution et la spécification des paramètres par nom.


Tâches de géotraitement dans les applications Web

Vous pouvez ajouter des fonctionnalités de géotraitement et d'analyse de données aux applications Web à l'aide des services de géotraitement ArcGIS. Chaque service de géotraitement contient une ou plusieurs tâches de géotraitement. Si vous parcourez le répertoire des services d'un serveur ArcGIS, vous pouvez trouver des services de géotraitement, les tâches au sein du service, ainsi que les paramètres et propriétés de chaque tâche. La rubrique Services REST de géotraitement fournit des informations sur la hiérarchie des ressources REST, et la rubrique Introduction aux tâches de géotraitement fournit plus d'informations sur les tâches de géotraitement, leurs paramètres et comment y accéder. Les API Web fournissent des objets et des méthodes pratiques pour accéder aux tâches de géotraitement et exécuter la fonctionnalité.

  1. Initialisez la tâche de géotraitement.
  2. Configurez les paramètres de la tâche.
  3. Exécutez la tâche.
  4. Rendre les résultats.

Ces quatre étapes permettent à l'application de communiquer avec le serveur, d'exécuter la tâche avec succès et de visualiser les résultats selon les besoins de l'application. La section ci-dessous montre comment mettre en œuvre les quatre étapes pour ajouter avec succès la fonctionnalité de géotraitement à l'aide de l'API Web ArcGIS pour Javascript. Bien que les déclarations d'objet, la syntaxe de méthode et la gestion des événements varient dans les deux autres API Web, le modèle en quatre étapes est commun et applicable à toutes les API Web. Les étapes vous aideront à comprendre les meilleures pratiques pour utiliser les tâches de géotraitement dans les applications Web.


8 réponses 8

La meilleure pratique pour la conception d'API RESTful est que les paramètres de chemin sont utilisés pour identifier une ou plusieurs ressources spécifiques, tandis que les paramètres de requête sont utilisés pour trier/filtrer ces ressources.

Voici un exemple. Supposons que vous implémentiez des points de terminaison d'API RESTful pour une entité appelée Car. Vous structureriez vos points de terminaison comme ceci :

OBTENIR /voitures
GET /cars/:id
POST /voitures
METTRE /voitures/:id
SUPPRIMER /voitures/:id

De cette façon, vous n'utilisez que des paramètres de chemin lorsque vous spécifiez la ressource à récupérer, mais cela ne trie/filtre en aucune façon les ressources.

Supposons maintenant que vous vouliez ajouter la possibilité de filtrer les voitures par couleur dans vos requêtes GET. Parce que la couleur n'est pas une ressource (c'est une propriété d'une ressource), vous pouvez ajouter un paramètre de requête qui fait cela. Vous ajouteriez ce paramètre de requête à votre OBTENIR /voitures demande comme ceci :

Ce point de terminaison serait mis en œuvre afin que seules les voitures bleues soient retournées.

En ce qui concerne la syntaxe, vos noms d'URL doivent être tous en minuscules. Si vous avez un nom d'entité qui est généralement composé de deux mots en anglais, vous utiliserez un trait d'union pour séparer les mots, pas un cas de chameau.

La façon fondamentale de penser à ce sujet est la suivante :

Un URI est un identifiant de ressource qui identifie de manière unique une instance spécifique d'un TYPE de ressource. Comme tout le reste dans la vie, chaque objet (qui est une instance d'un certain type) possède un ensemble d'attributs qui sont soit invariants dans le temps, soit temporels.

Dans l'exemple ci-dessus, une voiture est un objet très tangible qui a des attributs comme la marque, le modèle et le VIN - qui ne changent jamais, et la couleur, la suspension, etc. qui peuvent changer avec le temps. Donc, si nous encodons l'URI avec des attributs qui peuvent changer au fil du temps (temporel), nous pouvons nous retrouver avec plusieurs URI pour le même objet :

Et des années plus tard, si la couleur de cette même voiture passe au noir :

Notez que l'instance de voiture elle-même (l'objet) n'a pas changé - c'est juste la couleur qui a changé. Avoir plusieurs URI pointant vers la même instance d'objet vous obligera à créer plusieurs gestionnaires d'URI - ce n'est pas une conception efficace, et n'est bien sûr pas intuitive.

Par conséquent, l'URI ne devrait être composé que de parties qui ne changeront jamais et qui continueront à identifier de manière unique cette ressource tout au long de sa durée de vie. Tout ce qui peut changer doit être réservé aux paramètres de requête, en tant que tels :


DeCorps

Spécifie qu'un paramètre ou une propriété doit être lié à l'aide du corps de la demande.

Lorsque vous utilisez l'attribut FromBody, vous spécifiez que les données proviennent du corps du corps de la demande et non de l'URL/URI de la demande. Vous ne pouvez pas utiliser cet attribut avec les requêtes HttpGet, uniquement avec les requêtes PUT, POST et Delete. De plus, vous ne pouvez utiliser qu'une seule balise d'attribut FromBody par méthode d'action dans l'API Web (si cela a changé dans mvc core, je n'ai rien trouvé pour le soutenir).

FromRouteAttribute

Résumé : spécifie qu'un paramètre ou une propriété doit être lié à l'aide des données de route de la demande actuelle.

Essentiellement, FromRoute examinera les paramètres de votre route et extraira / liera les données en fonction de cela. Comme la route, lorsqu'elle est appelée en externe, est généralement basée sur l'URL. Dans les versions précédentes de l'API Web, cela est comparable à FromUri .

Cela essaierait donc de lier facilityId en fonction du paramètre de route du même nom.

Sur la base de votre dernière question, voici le code correspondant en supposant que vous souhaitez que 163 soit lié à facilityId et 10 aux paramètres de bande passante.

Si vous aviez un objet complexe dans l'un des paramètres et que vous vouliez l'envoyer comme corps de la demande Http, vous pourriez utiliser FromBody au lieu de FromRoute sur ce paramètre. Voici un exemple tiré de la création de votre première API Web avec ASP.NET Core MVC

Il existe également d'autres options dans MVC Core comme FromHeader et FromForm et FromQuery .


L'API JavaScript ne fait que mapper l'API REST dans un joli package, mais il n'y a rien d'unique à ce sujet. Vous devriez pouvoir appeler n'importe laquelle des fonctions de l'API REST avec jQuery en utilisant $.ajax . En regardant l'explorateur d'API, je vois qu'ils utilisent des paramètres de requête pour la plupart des choses, vous voudrez donc utiliser l'attribut de données pour tous les paramètres.

En fait, j'ai fini par implémenter cela un peu différemment, mais je pense que les deux méthodes fonctionnent aussi bien. La partie importante qui m'a causé du chagrin était le &routeattributes=all. Sans cela, les formes ne sont pas renvoyées, vous ne pouvez donc pas dessiner la polyligne, etc. Dans le document PDF, on parle d'attributs de réponse à quelques endroits, ce qui m'a vraiment gâché. En tout cas j'ai fait :


S'il existe des bonnes pratiques documentées, je ne les ai pas encore trouvées. Cependant, voici quelques directives que j'utilise pour déterminer où placer les paramètres dans une URL :

Les paramètres facultatifs ont tendance à être plus faciles à mettre dans la chaîne de requête.

Si vous souhaitez renvoyer une erreur 404 lorsque la valeur du paramètre ne correspond pas à une ressource existante alors je tendrais vers un paramètre de segment de chemin. par exemple. /customer/232 où 232 n'est pas un identifiant client valide.

Si toutefois vous souhaitez renvoyer une liste vide, lorsque le paramètre n'est pas trouvé, je suggère d'utiliser des paramètres de chaîne de requête. par exemple. /contacts?nom=dave

Si un paramètre affecte un sous-arbre entier de votre espace URI, utilisez un segment de chemin. par exemple. un paramètre de langue /en/document/foo.txt versus /document/foo.txt?language=en

Je préfère que les identifiants uniques soient dans un segment de chemin plutôt qu'un paramètre de requête.

Les règles officielles pour les URI se trouvent dans cette spécification RFC ici. Il existe également une autre spécification RFC très utile ici qui définit les règles de paramétrage des URI.

Réponse tardive mais j'ajouterai quelques informations supplémentaires à ce qui a été partagé, à savoir qu'il existe plusieurs types de "paramètres" pour une demande, et vous devez en tenir compte.

  1. Localisateurs - Par ex. des identifiants de ressources tels que des identifiants ou des actions/vues
  2. Filtres - Par ex. des paramètres qui permettent de rechercher, de trier ou d'affiner l'ensemble des résultats.
  3. État - Ex. identification de session, clés API, etc.
  4. Contenu - Par ex. données à stocker.

Regardons maintenant les différents endroits où ces paramètres pourraient aller.

  1. Demander des en-têtes et des cookies
  2. Chaîne de requête d'URL (vars "GET")
  3. Chemins d'URL
  4. Chaîne de requête de corps/multipart (vars "POST")

En général, vous souhaitez que l'état soit défini dans les en-têtes ou les cookies, selon le type d'informations d'état dont il s'agit. Je pense que nous pouvons tous être d'accord là-dessus. Utilisez des en-têtes http personnalisés (X-My-Header) si vous en avez besoin.

De même, le contenu n'a qu'un seul endroit auquel appartenir, qui se trouve dans le corps de la demande, soit sous forme de chaînes de requête, soit sous forme de contenu http multipart et/ou JSON. Ceci est cohérent avec ce que vous recevez du serveur lorsqu'il vous envoie du contenu. Donc, vous ne devriez pas être impoli et le faire différemment.

Des localisateurs tels que "id=5" ou "action=refresh" ou "page=2" auraient du sens d'avoir comme chemin d'URL, comme mysite.com/article/5/page=2 où vous savez en partie ce que chaque partie est censé signifier (les bases telles que article et 5 signifient évidemment obtenir les données de type article avec l'ID 5) et des paramètres supplémentaires sont spécifiés dans le cadre de l'URI. Ils peuvent être sous la forme page=2 , ou page/2 si vous savez qu'après un certain point dans l'URI, les "dossiers" sont des paires de valeurs-clés.

Les filtres vont toujours dans la chaîne de requête, car même s'ils font partie de la recherche des bonnes données, ils ne sont là que pour renvoyer un sous-ensemble ou une modification de ce que les localisateurs renvoient seuls. La recherche dans mysite.com/article/?query=Obama (sous-ensemble) est un filtre, tout comme /article/5?order=backwards (modification). Pensez à ce qu'il fait, pas seulement à son nom !

Si "view" détermine le format de sortie, alors il s'agit d'un filtre ( mysite.com/article/5?view=pdf ) car il renvoie une modification de la ressource trouvée plutôt que de se focaliser sur la ressource que nous voulons. S'il décide plutôt quelle partie spécifique de l'article nous pouvons voir ( mysite.com/article/5/view=summary ), alors il s'agit d'un localisateur.

Souviens-toi, en rétrécissant un ensemble de ressources est en train de filtrer. La localisation de quelque chose de spécifique dans une ressource est la localisation. duh. Le filtrage de sous-ensemble peut renvoyer n'importe quel nombre de résultats (même 0). La localisation trouvera toujours cette instance spécifique de quelque chose (si elle existe). Le filtrage des modifications renverra les mêmes données que le localisateur, sauf modifiées (si une telle modification est autorisée).

J'espère que cela a aidé à donner aux gens des moments eurêka s'ils ne savent pas où mettre des trucs !

Cela dépend d'une conception. Il n'y a pas de règles pour les URI chez REST sur HTTP (l'essentiel est qu'ils soient uniques). Souvent, il s'agit de la question du goût et de l'intuition.

J'adopte l'approche suivante :

  • élément de chemin d'URL : la ressource et son élément de chemin forment une traversée de répertoire et une sous-ressource (par exemple /items/ , /utilisateurs/éléments). En cas de doute, demandez à vos collègues s'ils pensent que la traversée et qu'ils pensent dans "un autre répertoire" l'élément de chemin le plus probable est le bon choix
  • Paramètre url : lorsqu'il n'y a pas vraiment de traversée (les ressources de recherche avec plusieurs paramètres de requête sont un très bon exemple pour cela)

OMI, les paramètres devraient être meilleurs en tant qu'arguments de requête. L'url est utilisée pour identifier la ressource, tandis que les paramètres de requête ajoutés pour spécifier quelle partie de la ressource vous voulez, tout état que la ressource doit avoir, etc.

Conformément à la mise en œuvre REST,

1) Variables de chemin sont utilisés pour l'action directe sur les ressources, comme un contact ou une chanson ex..
GET etc /api/ressource/ ou alors
GET etc /api/ressource/ renverra les données respectives.

2) Perms de requête/argument sont utilisés pour les ressources indirectes comme les métadonnées d'une chanson ex. GET /api/ressource/?metadata=genres il renverra les données de genres pour cette chanson particulière.

"Pack" et POST vos données dans le "contexte" fourni par l'univers-resource-locator, ce qui signifie #1 pour le bien du localisateur.

Attention aux limites avec #2. Je préfère les POST au #1.

note : les limitations sont discutées pour

p.s. ces limites sont basées sur les capacités du client (navigateur) et du serveur (configuration).

Selon la norme URI, le chemin concerne les paramètres hiérarchiques et la requête concerne les paramètres non hiérarchiques. Ofc. cela peut être très subjectif ce qui est hiérarchique pour vous.

Dans les situations où plusieurs URI sont attribués à la même ressource, j'aime mettre les paramètres - nécessaires à l'identification - dans le chemin et les paramètres - nécessaires pour construire la représentation - dans la requête. (Pour moi, de cette façon, il est plus facile de router.)

Pour la réduction de la carte, j'aime utiliser les approches suivantes :

C'est donc vraiment à vous (et à votre routeur côté serveur) de décider comment vous construisez vos URI.

remarque : pour mentionner que ces paramètres sont des paramètres de requête. Donc, ce que vous faites vraiment, c'est définir un langage de requête simple. Par des requêtes complexes (qui contiennent des opérateurs comme et, ou, supérieur à, etc.) je vous suggère d'utiliser un langage de requête déjà existant. Les capacités des modèles d'URI sont très limitées.

En tant que programmeur souvent côté client, je préfère l'argument de requête. De plus, pour moi, cela sépare le chemin de l'URL des paramètres, ajoute de la clarté et offre plus d'extensibilité. Cela me permet également d'avoir une logique séparée entre le bâtiment URL/URI et le générateur de paramètres.

J'aime ce que manuel aldana a dit à propos de l'autre option s'il y a une sorte d'arbre impliqué. Je peux voir des parties spécifiques à l'utilisateur être arborées comme ça.

Il n'y a pas de règles strictes et rapides, mais la règle empirique d'un point de vue purement conceptuel que j'aime utiliser peut se résumer brièvement comme ceci : un chemin d'URI (par définition) représente une ressource et les paramètres de requête sont essentiellement des modificateurs sur cette ressource . Jusqu'à présent, cela n'aide probablement pas. Avec une API REST, vous disposez des principales méthodes pour agir sur une seule ressource en utilisant GET , PUT et DELETE . Par conséquent, si quelque chose doit être représenté dans le chemin ou en tant que paramètre peut être réduit à savoir si ces méthodes ont un sens pour la représentation en question. Voudriez-vous raisonnablement METTRE quelque chose sur ce chemin et serait-il sémantiquement sain de le faire ? Vous pouvez bien sûr METTRE quelque chose à peu près n'importe où et plier le back-end pour le gérer, mais vous devriez METTRE ce qui équivaut à une représentation de la ressource réelle et non à une version inutilement contextualisée de celle-ci. Pour les collections, la même chose peut être faite avec POST. Si vous vouliez ajouter à une collection particulière, quelle serait une URL qui aurait du sens pour POST.

Cela laisse encore des zones d'ombre, car certains chemins pourraient indiquer le montant des ressources parentales pour les enfants, ce qui est quelque peu discrétionnaire et dépend de leur utilisation. La seule ligne dure que cela dessine est que tout type de représentation transitive doit être effectué à l'aide d'un paramètre de requête, car il n'aurait pas de ressource sous-jacente.

En réponse à l'exemple du monde réel donné dans la question d'origine (API Twitter), les paramètres représentent une requête transitive qui filtre sur l'état des ressources (plutôt qu'une hiérarchie). Dans cet exemple particulier, il serait tout à fait déraisonnable d'ajouter à la collection représentée par ces contraintes, et en outre, cette requête ne pourrait pas être représentée comme un chemin qui aurait un sens dans les termes d'un graphe d'objets.