learn how to use dynamics 365 as a web-based data sourcestarted+… · learn how to use dynamics...

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 [email protected]• Not covered today


mailto:[email protected]?subject=Web%20API%20authentication

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


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!


https://reenhanced-staging.api.crm.dynamics.com/api/data/v9.1/

Service Root URL – What is it?

Let’s paste it into a web browser and find out.

What could possibly go wrong?


Exploring Service Root URL


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?


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


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


https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/browse-your-metadata

Service Root URLWhat else do we see?


• 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

Exploring entityset as url


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?


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?


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!)


$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


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.

https://docs.microsoft.com/en-us/powerapps/developer/common-data-service/webapi/query-data-web-api

$filter parameter options

📝Only one $filter per request.Entire filter query must be passed in a single $filter param.


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')


📝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!


fetchXml example

Un-URL encoded:

URL encoded:

Online tool for encoding: https://meyerweb.com/eric/tools/dencoder/


<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

https://meyerweb.com/eric/tools/dencoder/

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


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

Exploring fetchXml


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?


/savedqueries

What do you see?

8/28/2019www.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…


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.)


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)


https://reenhanced-staging.api.crm.dynamics.com/api/data/v9.1/accounts(d7ee752c-f86a-e711-8115-c4346baceb24)

Questions?

8/28/2019

Contact Details:

Nick Hance

[email protected]

Twitter: @nhance

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:

[email protected]

www.reenhanced.com

https://docs.microsoft.com/en-us/powerapps/developer/common-data-service/webapi/query-data-web-api

https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/browse-your-metadata

http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html

learn how to use dynamics 365 as a web-based data sourcestarted+… · learn how to use dynamics...

Documents