Web API - External ID

1. První OID v URL cestě:

   Lze použít externalid místo oid, musí však být URL kódováno (např. dvojtečka jako %3A).

   http://localhost:81/demodata/countries/ext%3Ax_number_1?select=id

2. OID odkazovaných číselníků v těle dotazu:

   Při zadávání odkazů na číselníky lze místo oid použít externalid.

   {
   	"storecard_id": "ext:x_number_2"
   }

3. Změna řádků v kolekci:

   Externalid lze použít k identifikaci konkrétního řádku při jeho úpravě.

   {
   	"rows": {
   		"id": "ext:x_number_3",
   		"text": "test change"
   	}
   }

4. Mazání řádků v kolekci:

   Externalid lze použít k určení řádků k vymazání pomocí includeids nebo excludeids.

   {
   	"rows@delete": {
   		"includeids": ["ext:x_number_4"]
   	}
   }

5. Import a export dokumentů:

   Externalid lze použít při odkazování na dokumenty v importu nebo exportu.

   {
   	"input_documents": "ext:op_forimport_1",
   	"output_document": "ext:fv_forimportfromop_1"
   }

6. Dávkové zpracování:

   Při dávkovém zpracování operací update nebo delete lze používat externalid. URL musí být správně kódováno.

7. Operace proti serverovému stavu:

   Podpora pro externalid byla doplněna v operacích jako load, clone apod.

   Výjimka: Operace update dohledává externalid v cache (nikoliv v databázi), což znamená, že objekt musí být v cache načtený, jinak operace selže.

• Kolekce ExternalIDs nemá žádné podkolekce. Syntaxe ext: na kolekci ExternalIDs není podporována.
• Podpora externalid nebyla implementována na několika místech, která nejsou určena k použití v Web API nebo ke skriptování.

# ExternalID je možné používat v různých místech API, kde se běžně používá odkaz na objekt, tzv OID.
# Před vlastním externalid je nutné uvést prefix ext:.
# Systém v takovém případě zkusí dohledat OID pomocí ExternalID. Pokud se nenajde, vyvolá se vyjímka.
# ExternalID jsou v rámci jedné třídy business objektů unikátní - je to hlídáno unikátností
# v databázi.

import base64
import json
import sys
import uuid

import requests
from http_constants.headers import HttpHeaders

session = requests.Session()
headers = {}
headers[HttpHeaders.CONTENT_TYPE] = HttpHeaders.CONTENT_TYPE_VALUES.json
headers[HttpHeaders.AUTHORIZATION] = "Basic " + (
	base64.urlsafe_b64encode(("tester" + ":" + "testerp").encode("utf-8"))
).decode("utf-8")


# Vytvoření nových náhodných ExternalID pro demonstrační použití.
EXTID_FV = "fv_" + str(uuid.uuid4())
EXTID_FV_ROW = "fvrow_" + str(uuid.uuid4())
EXTID_FIRM = "firm_" + str(uuid.uuid4())


# ExternalID je implementované jako kolekce pro skoro každý business objekt a založení nebo změna
# se provádí naprosto stejně jako u jiných kolekcí. A také se zde nepoužívá prefix - tak je se zde uvede
# tak se i uloží, prefix by se v takovém případě bral jako součást ExternalID.

print("\ncreate new issued invoice with externalids:")
body = {
	"firm_id": "3000000101",
	"docqueue_id": "5600000101",
	"storedocqueue_id": "P600000101",
	"description": "text fv 1",
	"externalids": [
		{
			"externalid": f"{EXTID_FV}",
		}
	],
	"rows": [
		{
			"rowtype": 0,
			"text": "original text",
			"division_id": "2100000101",
			"externalids": [{"externalid": f"{EXTID_FV_ROW}"}],
		}
	],
}
response = session.post(
	url="http://localhost:81/demodata/issuedinvoices?select=id,description&expand=externalids,rows(text)",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 201:
	sys.exit(0)
response_body = response.json()
fv_id = response_body["id"]


# ExternalID lze použít v cestě - zatím jen u prvního ID a je třeba ho mít url encoded
# (%3A je dvojtečka ... ale vzhledem k tomu, že může obsahovat v podstatě libovolné znaky,
# je nutné ho urlencodovat celé).
print("\nchange previously created fv by externalid in url:")
body = {"description": "changed via url externalid"}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/ext%3A{EXTID_FV}?select=id,description",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)


# ExternalID lze použít při změně řádky v kolekci. V URL je nyní použité OID, ale
# samozřejmě lze použít ExternalID i v url jako u předchozího příkladu.
print("\nchange row in previously created fv by externalid in collection:")
body = {
	"rows": [
		{
			"id": f"ext:{EXTID_FV_ROW}",
			"text": "change row by externalid",
		}
	],
}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/{fv_id}?expand=rows(id, text)",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)


# ExternalID lze použít pro smazání řádku v kolekci.
print("\ndelete row in previously created fv by externalid in collection:")
body = {
	"rows@delete": {
		"includeids": [f"ext:{EXTID_FV_ROW}"],
	},
}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/{fv_id}?expand=rows",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)


# ExternalID lze použít při změně BO pro identifikaci odkazu do číselníku.

# Nejdřív na nějakou firmu nasetujeme nové ExternalID
print("\nnew externalid for firm:")
body = {
	"externalids": [
		{"externalid": f"{EXTID_FIRM}"},
	],
}
response = session.put(
	url="http://localhost:81/demodata/firms/K000000101?expand=externalids",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)

# A pak změním firmu na FV pomocí tohoto ExternalID
print("\nchange firm on previously created fv by externalid:")
body = {
	"firm_id": f"ext:{EXTID_FIRM}",
}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/{fv_id}?select=firm_id",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)

Generická podpora: Ve většině míst Web API byla podpora externalid implementována, ale pokud se najdou nová místa, podpora může být doplněna v budoucnu.

Výhody externalid:

• Jednoznačná identifikace záznamů bez závislosti na interním ID (oid).
• Flexibilita při přenášení identifikátorů mezi systémy.