learn how to use dynamics 365 as a web-based data sourcestarted+… · learn how to use dynamics...
Post on 22-May-2020
3 Views
Preview:
TRANSCRIPT
Getting Started With The Web APILearn how to use Dynamics 365 as a web-based data source
Presented by: Nick Hance
Who are you?
You’ll benefit from this if…
• You know what an API is
• You have built/know what an API can do for you
• You want to learn more about what you can do with the Dynamics 365 Web API
8/28/2019 www.reenhanced.com
What is the Dynamics 365 Web API?
• REST based API
• Returns JSON data
• Supports Read (GET), Create (POST), Update (PATCH), Delete (DELETE)
• Today we’ll cover GET requests using cookie authentication
• External authentication via OAuth.• Somewhat painful depending on needs.• Contact me if you have questions nhance@reenhanced.com• Not covered today
8/28/2019 www.reenhanced.com
Hi! I’m Nick Hance
• I rescue struggling tech projects.
• Building web apps since 1999.
• Founded reenhanced in 2005.
• Over 70 employees. Fully remote.
• “Full-Stack” developer unintimidated by any tech challenge
8/28/2019 www.reenhanced.com
Interesting fact: I like running! I ran a 50 mile trail race
on June 1st.
Accessing your API
• Go to Settings -> Customizations -> Developer Resources
• You’re looking for Service Root URL
• It looks like this:• https://reenhanced-staging.api.crm.dynamics.com/api/data/v9.1/
Feel free to explore your own instance as we go!
8/28/2019 www.reenhanced.com
Service Root URL – What is it?
Let’s paste it into a web browser and find out.
What could possibly go wrong?
8/28/2019 www.reenhanced.com
Exploring Service Root URL
8/28/2019 www.reenhanced.com
Note:
• We are re-using session
authentication.
• This means you’ll need
Dynamics open in another tab.
• Paste the URL into a new tab.
What is this?
8/28/2019 www.reenhanced.com
Service Root URL is our API base path!
It returns two types of data
• First attribute is an @odata link.
• Everything else are components in our
system.
Let’s explore the odata link
Exploring $metadata
8/28/2019 www.reenhanced.com
Sequences shortened.
This is a large document! (multiple
megabytes)
$metadata describes your system!
• Cool! You can spend hours reviewing this to learn all about how your Dynamics instance is put together.
• Metadata also describes the API, which is a lot deeper than we have time for today.
📤 Outside of this talk’s scopeRead more here: https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/browse-your-metadata
8/28/2019 www.reenhanced.com
Service Root URLWhat else do we see?
8/28/2019 www.reenhanced.com
• value contains a list of entities.
• kind is EntitySet
• url -- This is interesting.
• Let’s treat url as a relative URL, and tack it
on the end of our request
GET /api/data/v9.1/accounts
This shows us ALL accounts in our system!!
😱 This could be a LOT of data.
🐌 Using this request in an app could be really slow.
⏩Can we make our request faster?
8/28/2019 www.reenhanced.com
Refining a query – An example
We can use $select and $top to get only the name of the top 3 accounts.
But what are the other attributes?
8/28/2019 www.reenhanced.com
What is @odata.etag?
Every entity instance returns a unique @odata.etag attribute.
What does this mean to us?
🔑 Useful as cache key.
🗺 ETag is information about the full entity.(Not the data returned in your query!)
8/28/2019 www.reenhanced.com
$select limits attributes. What else is there?Key Value Description
$select attribute[, attribute[, attribute]] Only the named attributes here will be returned. Primary key and etag always come back as well.
$top Number of records to return Limits the results to only this many
$filter <lots of options!> Covered on another slide
$orderby attribute [asc|desc], [attribute asc|desc] Defines the order the records are returned
fetchXml Url-encoded Fetch XML EMBED FETCHXML! Wow! Makes for a very long url. Make sure to url-encode
8/28/2019 www.reenhanced.com
More info: https://docs.microsoft.com/en-us/powerapps/developer/common-data-service/webapi/query-data-web-api
📝Attribute is schema name. You cannot use display name.
$filter parameter options
📝Only one $filter per request.Entire filter query must be passed in a single $filter param.
8/28/2019 www.reenhanced.com
Operator Description Example
eq Equal $filter=revenue eq 10000
ne Not Equal $filter=revenue ne 10000
gt Greater Than $filter=revenue gt 10000
geGreater Than or
Equal$filter=revenue ge 10000
lt Less Than $filter=revenue lt 10000
le Less Than or Equal $filter=revenue le 10000
and Logical And $filter=revenue gt 1000 and revenue lt 25000
or Logical or $filter=contains(name, 'sample') or contains(name, 'test')
not Logical Negation $filter=not contains(name, 'test')
( ) Precedence$filter=(contains(name, 'sample') or contains(name, 'test')) and revenue gt 500
$filter functionsFunction Example
contains $filter=contains(name, 'coffee')
endswith $filter=endswith(name, 'inc')
startswith $filter=startswith(name, 'a')
8/28/2019 www.reenhanced.com
📝Search strings are NOT case sensitive. Thank goodness!
Yes, you are actually expected to put apostrophes into your url. Spaces are not required. You can url encode it if you like.
fetchXml. In. A. URL. (Seriously!)
• You can use fetchXml in a URL query.
• Make sure to url-encode it
• Bless your eyes if you ever have to maintain the full url. Don’t manage by hand if at all possible.
📝You can combine $filter (and others) with fetchXml!
Example time!
8/28/2019 www.reenhanced.com
fetchXml example
Un-URL encoded:
URL encoded:
Online tool for encoding: https://meyerweb.com/eric/tools/dencoder/
8/28/2019 www.reenhanced.com
<fetch version="1.0" output-format="xml-platform" mapping="logical"><entity name="account"><attribute name="name" /><attribute name="primarycontactid" /><attribute name="telephone1" /><attribute name="accountid" /><order attribute="name" descending="false" />
</entity></fetch>
%3Cfetch%20version%3D%221.0%22%20output-format%3D%22xml-platform%22%20mapping%3D%22logical%22%3E%3Centity%20name%3D%22account%22%3E%3Cattribute%20name%3D%22name%22%20%2F%3E%3Cattribute%20name%3D%22primarycontactid%22%20%2F%3E%3Cattribute%20name%3D%22telephone1%22%20%2F%3E%3Cattribute%20name%3D%22accountid%22%20%2F%3E%3Corder%20attribute%3D%22name%22%20descending%3D%22false%22%20%2F%3E%3C%2Fentity%3E%3C%2Ffetch%3E
Using fetchXml in a request
A valid url:
https://reenhanced-staging.api.crm.dynamics.com/api/data/v9.1/accounts?fetchXml=%3Cfetch%20version=%221.0%22%20output-format=%22xml-platform%22%20mapping=%22logical%22%3E%3Centity%20name=%22account%22%3E%3Cattribute%20name=%22name%22%20/%3E%3Cattribute%20name=%22primarycontactid%22%20/%3E%3Cattribute%20name=%22telephone1%22%20/%3E%3Cattribute%20name=%22accountid%22%20/%3E%3Corder%20attribute=%22name%22%20descending=%22false%22%20/%3E%3C/entity%3E%3C/fetch%3E
8/28/2019 www.reenhanced.com
Not all Entities are the same!
A close look at our Service Root Url shows interesting entries!
Let’s look at savedqueries. Any guess at what these are?
8/28/2019 www.reenhanced.com
A Saved Query is a View!
• Saved queries shows ALL saved views across all entities!
• $filter=returnedtypecode eq ‘entitytype’ will get you all views for an entity!!
Look Closer…
8/28/2019 www.reenhanced.com
Combining what I’ve learned1. You can get full information about any entity via the Web API.
2. You can use $select and $filter params (and others) to refine the JSON we receive.
3. A Saved Query is the same thing as a System View
4. You can use fetchxml in a web api query. Saved Queries give us fetchxml.
Therefore… You can allow administrators configuration of data in a web API powered app using a system view!!
How?
1. First request gets the saved view and extracts fetchXml from result.
2. Second request uses fetchXml in query.
3. Configuration is then managed without code!
(This can be used in flow apps or any other systems that use the Web API.)
8/28/2019 www.reenhanced.com
Other interesting
facts
• You can use older versions of the API from newer versions!
• Custom Entities are accessible over Web API!
• When using $select, the primary key is always returned!
• There is another operator called $expand. What does it do?
• $expand can be used with relationship schema names! (These don’t appear in the full JSON entity)
• For most entities, you can Read/Write/Append over API!
• Endpoints for you to explore: /systemforms, /EntityDefinitions, /RelationshipDefinitions
One more thing
You can also get just a single entity. Put the primary key in parentheses
Example: https://reenhanced-staging.api.crm.dynamics.com/api/data/v9.1/accounts(d7ee752c-f86a-e711-8115-c4346baceb24)
8/28/2019 www.reenhanced.com
Bonus Content (Download only!)
Helpful links:
• Query data using web api: https://docs.microsoft.com/en-us/powerapps/developer/common-data-service/webapi/query-data-web-api
• About metadata: https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/browse-your-metadata
• Odata 4.0 (this is the language of the api): http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html
• Contact me. I am always happy to share ideas:
nhance@reenhanced.com
www.reenhanced.com
top related