Customizing API Requests
The following properties provide the granular control useful for integrating with nonstandard APIs or to access more advanced OData functionality.
- CustomUrlParams: Set this to append query string parameters onto the request that the cmdlet builds.
Note that if this property is not set you must set Url to the service document to avoid an error.
- ContinueOnError: The cmdlet builds batch requests to OData 4.0 services when batch APIs in the underlying driver interface are invoked; for example, when your application makes a batch request.
When this property is set, errors are returned in a temporary table to avoid breaking execution.
- UseEtags: Etags can be used by OData clients to check if a resource has changed on the server and avoid concurrency problems. If you do not need to surface this functionality or if your OData service does not return Etags, set this property to false.
- Cookies: If you need to provide cookies obtained outside the cmdlet, you can set them in this value.
- CustomHeaders: You can use this property to add any value to any HTTP request header.
Fine-Tuning Data Access
Set the following properties to control how the cmdlet models OData APIs as a database:
- NavigationPropertiesAsViews: By default, the cmdlet models navigation properties as views. This enables access to related entities, even though these entities may not be linked by a foreign key in your OData service.
- SupportsExpand: If your API does not support the $expand parameter, set this property to avoid an error when NavigationPropertiesAsViews is set. If this is the case for your API, specify the base entity's primary key in the WHERE clause to access navigation properties.
- DataFormat: Set this property to JSON or XML. Otherwise, the cmdlet uses the default format defined by the service.
- ODataVersion: Use this to override the version detected by the cmdlet. This is useful if your application supports an older OData version.
- UseIdUrl: By default the cmdlet returns the direct URL to an entity as the primary key. By setting this to false, the entity key is returned.
- UseSimpleNames: Set this to true to return only alphanumeric characters in column names. This can help you to avoid SQL escapes and errors in SQL-based tools.
- ServerTimeZone: By default, the cmdlet assumes the server's Edm.DateTime values are GMT and converts them to and from the installed machine's local timezone accordingly. If the server's Edm.DateTime values are known to apply to a different timezone, then set this property to that timezone (i.e. EST).
Customizing the SSL Configuration
By default, the cmdlet attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.
Connecting Through a Firewall or Proxy
To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.
In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.
Set the following properties:
- To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
- To tunnel the connection, set FirewallType to TUNNEL.
- To authenticate, specify FirewallUser and FirewallPassword.
- To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.
Troubleshooting the Connection
To show cmdlet activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the cmdlet's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
- The certificate presented by the server cannot be validated: This error indicates that the cmdlet cannot validate the server's certificate through the chain of trust. If you are using a self-signed certificate, there is only one certificate in the chain.
To resolve this error, you must verify yourself that the certificate can be trusted and specify to the cmdlet that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.